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Preface 



TSO Extensions Guide to Writing a Terminal Monitor Program or a Command 
Processor describes features of TSO/E that each installation can replace, modify, 
or add to adapt the command system to the installation's particular needs. This 
book is intended for programmers who are responsible for modifying portions of 
TSO/E. It documents TSO Extensions for both MVS/Extended Architecture 
(MVS/XA) and MVS/370. The major differences between TSO/E running under 
MVS/XA and MVS/370 are explained in "MVS/Extended Architecture 
Considerations." 

The book discusses the terminal monitor program and the command processors 
from the viewpoint of the TSO/E system programmer's ability to replace or 
modify them. It describes the programming features provided within TSO/E for 
user-written terminal monitor programs, command processors, and application 
programs. These features include: 

• Service routines 

• Macro instructions 

• SVCs 

This book contains the following information required by a programmer: 

• Writing a TSO terminal monitor program 

• Writing a TSO command processor 

• Writing a program that uses TSO to: 

— Invoke another program or TSO command processor 

— Use CLIST variables 

It also discusses: 

• The functions that a terminal monitor program or a command processor 
should provide for the TSO/E user. 

• The macro instructions that provide these functions. 

• The service routines that can be used to provide these functions. 
The book contains the following eighteen chapters: 

1 . Introduction 

2. Terminal Monitor Program 

3. Command Processors 
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4. MVS/Extended Architecture Considerations 

5. TSO Service Routine (IKJEFTSR) 

6. Program Access To CLIST Variables--IKJCT441 

7. Processing Terminal Requests ~ The TSO Service Routines 

8. Message Handling 

9. Attention Interruption Handling -- The ST AX Service Routine 

10. Dynamic Allocation of Data Sets - The Dynamic Allocation Interface 
Routine (DAIR) 

11. Using BSAM or QSAM for Terminal I/O 

12. Using the TSO I/O Service Routines for Terminal I/O 

13. Using the TGET/TPUT/TPG SVC for Terminal I/O 

14. Using Terminal Control Macro Instructions 

15. Command Scan and Parse - Determining the Validity of Commands 

16. Catalog Information Routine (IKJEHCIR) 

17. Default Service Routine (IKJEHDEF) 

18. Testing a Newly- Written TMP or CP -- The TEST Command 

The first three chapters describe the functions performed by terminal monitor 
programs and command processors. The fourth chapter describes programming 
considerations for MVS/XA systems. The fifth chapter describes a TSO/E 
interface that allows unauthorized programs to invoke programs or TSO 
commands that will run under TSO/E regardless of whether they are authorized 
or not authorized. The sixth chapter describes a TSO/E interface that allows TSO 
to access CLIST variables from application programs. The seventh chapter 
describes how to interface with the TSO service routines to process terminal 
requests. The eighth chapter describes TSO messages. 

The next ten chapters describe the macro instructions and service routines that a 
programmer can use to provide the required functions. These macro instructions 
and service routines can be used to: 

• Issue messages 

• Schedule and process attention interruptions 

• Allocate, free, concatenate, and deconcatenate data sets during program 
execution 

• Provide I/O between a program and a terminal 

• Control terminal functions and attributes 
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# Determine the validity of commands, subcommands, and operands entering 
the system 

# Retrieve information from the system catalog 

# Construct a fully-qualified data set name 

The last chapter describes the TEST command and how you can use TEST to test 
a newly written terminal monitor program (TMP) or command processor (CP). 

Prerequisite and Reference Publications 

This book assumes you are familiar with the structure of TSO. You need the 
following publications for reference: 

For MVS/Extended Architecture 

MVS I Extended Architecture Data Management Macro Instructions, GC26-4014 

MVS J Extended Architecture Data Management Services, GC26-4013 

MVS I Extended Architecture VSAM Programmer's Guide, GC26-4015 

MVS/Extended Architecture System Programming Library: Data Management, 
GC26-4010 

System Programming Library: TSO Extensions Planning and Installation Volume 
1, SC28-1379 

System Programming Library: TSO Extensions User Exits and Modifications 
Volume 2, SC28-1380 

System Programming Library: TSO Extensions Command and Macro Reference 
Volume 3, SC28-1381 

Data Areas 

(for MVS/System Product Version 2 JES2) LYB8-1191 
(for MVS/System Product Version 2 JES3) LYB8-1195 

Macro Usage Table 

(for MVS/System Product Version 2 JES2) LYB8-1193 
(for MVS/System Product Version 2 JES3) LYB8-1197 

Symbol Usage Table 

(for MVS/System Product Version 2 JES2) LYB8-1192 
(for MVS/System Product Version 2 JES3) LYB8-1196 

TSO Extensions Command Language Reference, SC28-1307 

TSO Extensions Command Processor Logic, Volume I: ACCOUNT, LY28-1503 
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For MVS 370 



TSO Extensions Command Processor Logic, Volume II: EDIT, LY28-1504 

TSO Extensions Command Processor Logic, Volume III: TEST, LY28-1137 

TSO Extensions Command Processor Logic, Volume IV, LY28-1506 

TSO Extensions Terminal Monitor Program and Service Routines Logic, 
LY28-1308 

TSO Extensions User's Guide, SC28-1333 

TSO Extensions Terminal Messages, GC28-1310 

MVS j Extended Architecture System Programming Library: 31-Bit Addressing, 
GC28-1158 

System/370 Extended Architecture Principles of Operation, SA22-7085 

Refer to MVS/ System Product Version 2 General Information Manual, GC28-1118 
for the order numbers of the following MVS/XA books on the level that you are 
using: 

MVS/ Extended Architecture System Programming Library: Initialization and 
Tuning 

MVS/ Extended Architecture JCL 

MVS/ Extended Architecture System Programming Library: System Macros 
and Facilities 



OS/VS2 MVS Data Management Macro Instructions, GC26-3793 

OS/VS2 MVS Data Management Services Guide, GC26-3783 

OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide, GC26-3838 

OS/VS2 System Programming Library: Data Management, GC26-3830 

System Programming Library: TSO Extensions Planning and Installation Volume 
1, SC28-1379 

System Programming Library: TSO Extensions User Exits and Modifications 
Volume 2, SC28-1380 

System Programming Library: TSO Extensions Command and Macro Reference 
Volume 3, SC28-1381 

TSO Extensions User's Guide, SC28-1333 

Data Areas, LYB8-1119 

Macro Usage Table, LYB8-1120 



VI TSO/E Guide to Writing a TMP or a CP 



Symbol Usage Table, LYB8-1121 

TSO Extensions Command Language Reference, SC28-1307 

0S/VS2 TSO Command Processor Logic, Volume I: ACCOUNT, SY28-0651 

0S/VS2 TSO Command Processor Logic, Volume II: EDIT, SY33-8548 

0S/VS2 TSO Command Processor Logic, Volume III: TEST, SY35-0004 

0S/VS2 TSO Command Processor Logic, Volume IV, SY28-0652 

0SJVS2 TSO Terminal Monitor Program and Service Routines Logic, GC28-0645 

TSO Extensions Terminal Messages, GC28-1310 

System 370 1 Principles of Operation, GA22-7000 

Refer to MVSj System Product Version 1 General Information Manual, GC28-1025 
for the order numbers of the following MVS/370 books on the level that you are 
using: 

OS/VS2 System Programming Library: Initialization and Tuning Guide 

0S/VS2JCL 

OS/VS2 System Programming Library: Supervisor 



For MVS/Extended Architecture and MVS/370 



Referenced Products 



System Programming Library: TSO Extensions Planning and Installation Volume 
I, SC28-1379 

System Programming Library: TSO Extensions User Exits and Modifications 
Volume 2, SC28-1380 

System Programming Library: TSO Extensions Command and Macro Reference 
Volume 3, SC28-1381 

TSO Extensions User's Guide, SC28-1333 

TSO Extensions Command Language Reference, SC28-1307 

TSO Extensions Terminal Messages, GC28-1310 



1. MVS/Extended Architecture (MVS/XA) refers to Data Facility Product 
(5665-284) and MVS/System Product Version 2 - JES2 (5740-XC6) or 
MVS/System Product Version 2 - JES3 (5665-291) 

2. VTAM, TSO/VTAM, and ACF/VTAM refers to the program product 
ACF/VTAM Version 2 (5665-280). 

3. TCAM and TSO/TCAM refers to the program product ACF/TCAM Version 
2 Release 4 (5735-RC3). 

4. TSO/E refers to the program product TSO Extensions (5665-285). 



Preface Vll 



viii TSO/E Guide to Writing a TMP or a CP 



Contents 



Chapter 1. Introduction 1-1 

The Terminal Monitor Program (TMP) and Command Processors 1-1 

Basic Functions of Terminal Monitor Programs and Command Processors 1-2 

Communicating with the User 1-3 

Passing Control to Command and Subcommand Processors 1-3 

Invoking Programs or Commands 1-4 

Responding to Abnormal Terminations 1-4 

Responding to Attention Interruptions 1-4 

Other Functions Provided with TSO/E 1-5 

Dynamic Allocation of Data Sets 1-5 

Testing a TMP or a CP 1-6 

TSO Service Routine 1-6 

Program Interface to TSO/E Command Processors or Other Programs 1-6 

Chapter 2. The Terminal Monitor Program 2-1 

Terminal Monitor Program Initialization 2-2 
Requesting a Command 2-3 
Intercepting an ABEND 2-5 

Intercepting a Subtask ABEND 2-6 

Intercepting a TMP Task ABEND 2-7 
Processing an Attention Interruption 2-8 

Parameters Received by Attention Handling Routines 2-9 
The Attention Exit Parameter List 2-11 
The Terminal Attention Interrupt Element (TAIE) 2-11 
Processing a STOP Command 2-12 

Chapter 3. Command Processors 3-1 

Adding Commands to TSO 3-2 

Command Processor Coding Conventions 3-2 

Command Processor Use of the TSO Service Routines 3-2 

STACK Service Routine 3-3 

Catalog Information Routine 3-3 

Default Service Routine 3-4 

GETLINE Service Routine 3-4 

PUTLINE Service Routine 3-4 

PUTGET Service Routine 3-4 

IKJEFF02 Message Issuer Service Routine 3-5 

DAIR Service Routine 3-5 

Command Scan Service Routine 3-5 

Parse Service Routine 3-6 

Prompt Mode HELP Function 3-6 
ESTAE/ESTAI Exit Routine ~ Intercepting an ABEND 3-7 
Linkage Considerations 3-7 



Contents IX 



Command Processor Functions that Rely on Exit Routine Support 3-8 

Guidelines for ESTAE and ESTAI Exit Routines 3-8 
Attention Exit Routines 3-9 
The HELP Data Set 3-10 

Attributes of SYS1. HELP 3-10 

Format of HELP Members 3-10 
Private HELP Data Sets 3-11 
Updating SYS 1. HELP 3-11 

Writing HELP Members 3-11 

Updating Existing HELP Members 3-15 

Chapter 4. MVS/Extended Architecture Considerations 4-1 

31 -Bit Addressing - General Interface Considerations 4-1 

AMODE = 24, RMODE = 24 4-2 

AMODE = ANY, RMODE = 24 4-2 

AMODE = 31 4-2 
Specific Interfaces and Functions 4-3 

Control Program Interfaces 4-3 

Service Routine Interfaces 4-3 

Macro Interfaces 4-4 

31 -Bit Indirection Symbol 4-8 

Chapter 5. Invoking Other Programs or Commands With the TSO Service 
Routine 5-1 

TSO Service Routine 5-1 

Program Interface to TSO Commands or Programs 5-2 
Invoking the TSO Service Routine 5-2 
TSO Service Routine Parameters 5-4 

Chapter 6. Program Access to CLIST Variables 6-1 

Update or Create a CLIST Variable Value 6-3 

Update a CLIST Variable Value Only 6-5 

Return the Value of a CLIST Variable 6-8 

Return all Active CLIST Variables and their Values 6-11 

Chapter 7. Processing Terminal Requests - The TSO Service Routines 7-1 

Interfacing with the TSO Service Routines 7-2 
The Command Processor Parameter List 7-2 
Passing Control to the TSO Service Routines 7-3 
The CALLTSSR Macro Instruction 7-4 
Example 7-5 

Chapter 8. Message Handling 8-1 

Message Levels 8-1 

Effects of the Input Source on Message Processing 8-2 

TSO Message Issuer Routine (IKJEFF02) 8-3 

Standard Format of Input Parameter List 8-4 
Extended Format of Input Parameter List 8-5 
IKJTSMSG - Describes Text and Insert Locations 8-7 

Chapter 9. Attention Interruption Handling — The ST AX Service Routine 9-1 

Specifying a Terminal Attention Exit - The STAX Macro Instruction 9-4 

The STAX Parameter List 9-7 

Coding Example of the STAX Macro Instruction 9-8 



X TSO/E Guide to Writing a TMP or a CP 



Return Codes from the ST AX Service Routine 9-10 

Chapter 10. Dynamic Allocation of Data Sets - The Dynamic Allocation Interface 
Routine (DAIR) 10-1 
Considerations 10-1 
Using DAIR 10-2 

The DAIR Parameter List (DAPL) 10-4 
The DAIR Parameter Block (DAPB) 10-5 

Code X'00' - Determine if DDNAME or DSNAME Allocated 10-6 
Code X'04' - Determine if DSNAME Allocated or in System 

Catalog 10-7 
Code X'08' - Allocate a Data Set by DSNAME 10-8 
Code X'OC - Concatenate the Specified DDNAMES 10-11 
Code X'10' - Deconcatenate the Indicated DDNAME 10-11 
Code X'14' - Return Qualifiers for the Specified DSNAME 10-12 
Code X'18' - Free the Specified Data Set 10-12 
Code X'lC - Allocate the Specified DDNAME to the Terminal 10-14 
Code X'24' - Allocate a Data Set by DDNAME 10-14 
Code X'28' - Perform a List of DAIR Operations 10-17 
Code X'2C - Mark Data Sets as Not in Use 10-18 
Code X'30' - Allocate a SYSOUT Data Set to the Message Class 10-18 
Code X'34' - Associate DCB Parameters with a Specified Name 10-20 
DAIRACB - DAIR Attribute Control Block 10-21 
Return Codes from DAIR 10-23 
Return Codes from Dynamic Allocation 10-24 
DAIRFAIL Routine (IKJEFF18) 10-24 
GNRLFAIL/VSAMFAIL Routine (IKJEFF19) 10-26 

Chapter 11. Using BSAM or QSAM for Terminal I/O 11-1 
BSAM/QSAM Macro Instructions 11-1 
SAM Terminal Routines 11-2 

GET 11-3 

PUTandPUTX 11-3 

READ 11-3 

WRITE 11-4 

CHECK 11-4 
Record Formats, Buffering Techniques, and Processing Modes 11-4 
Specifying Terminal Line Size 11-4 
End-of-File (EOF) for Input Processing 11-5 
Modifying DD Statements for Batch or TSO Processing 11-5 

Chapter 12. Using the TSO I/O Service Routines for Terminal I/O 12-1 

The Input/Output Parameter List 12-2 
Passing Control to the I/O Service Routines 12-3 
The I/O Service Routine Macro Instructions 12-4 
STACK - Changing the Source of Input 12-5 

The STACK Macro Instruction - List Form 12-5 
The STACK Macro Instruction - Execute Form 12-7 
Sources of Input 12-11 
Building the STACK Parameter Block 12-12 
Building the List Source Descriptor (LSD) 12-15 
Return Codes from STACK 12-20 
GETLINE - Getting a Line of Input 12-21 

The GETLINE Macro Instruction - List Form 12-21 



Contents XI 



The GETLINE Macro Instruction - Execute Form 12-23 

Sources of Input 12-26 , 

End of Data Processing 12-27 ^ 

Building the GETLINE Parameter Block 12-27 

Input Line Format - The Input Buffer 12-28 

Examples of GETLINE 12-30 

Return Codes from GETLINE 12-32 
PUTLINE - Putting a Line Out to the Terminal 12-33 

The PUTLINE Macro Instruction - List Form 12-34 

The PUTLINE Macro Instruction - Execute Form 12-37 

Building the PUTLINE Parameter Block 12-42 

Types and Formats of Output Lines 12-44 
Passing the Message Lines to PUTLINE 12-49 

PUTLINE Message Line Processing 12-51 

Return Codes from PUTLINE 12-58 
PUTGET - Putting a Message Out to the Terminal and Obtaining a Line of 
Input in Response 12-58 

The PUTGET Macro Instruction - List Form 12-59 

The PUTGET Macro Instruction - Execute Form 12-63 

Building the PUTGET Parameter Block (PGPB) 12-69 

Types and Formats of the Output Line 12-71 

Passing the Message Lines to PUTGET 12-72 

PUTGET Processing 12-74 

Input Line Format - The Input Buffer 12-76 

An Example of PUTGET 12-77 

Return Codes from PUTGET 12-81 

Chapter 13. Using the TGET/TPUT/TPG SVC for Terminal I/O 13-1 ( 

The TPUT Macro Instruction - Writing a Line to the Terminal 13-1 

Return Codes from TPUT 13-7 
The TPG Macro Instruction - Writing a Line Causing Immediate 
Response 13-7 

Return Codes from TPG 13-9 
The TGET Macro Instruction - Getting a Line from the Terminal 13-10 

Return Codes from TGET 13-12 
TGET/TPUT/TPG Parameter Formats 13-13 
Coding Examples of TGET and TPUT Macro Instructions 13-17 

Examples of TPUT and TGET Using the Default Values 13-17 

Example of TPUT Macro Instruction - Buffer Address and Buffer Length in 
Registers 13-19 

Example of the TGET Macro Instruction - Register Format 13-20 

Chapter 14. Using Terminal Control Macro Instructions 14-1 
GTDEVSIZ ~ Get Device Size 14-2 
GTSIZE ~ Get Terminal Line Size 14-2 
GTTERM ~ Get Terminal Attributes 14-3 
RTAUTOPT ~ Restart Automatic Line Numbering or Character 

Prompting 14-4 
SPAUTOPT ~ Stop Automatic Line Numbering or Character 

Prompting 14-5 
ST ATTN - Set Attention Simulation 14-6 
STAUTOCP - Start Automatic Character Prompting 14-8 

STAUTOLN - Start Automatic Line Numbering 14-9 ( 

STBREAK ~ Set Break 14-10 



Xll TSO/E Guide to Writing a TMP or a CP 



STCC ~ Specify Terminal Control Characters 14-12 
STCLEAR -- Set Display Clear Character String 14-14 
STCOM - Set Inter-Terminal Communication 14-15 
STFSMODE - Set Full-Screen Mode 14-15 
STLINENO ~ Set Line Number 14-17 
STSIZE ~ Set Terminal Line Size 14-18 
STTIMEOU ~ Set Time Out Feature 14-20 
STTMPMD - Set Terminal Display Manager Options 14-21 
STTRAN ~ Set Character Translation 14-22 
TCLEARQ ~ Clear Buffers 14-24 

Chapter 15. Command Scan and Parse — Determining the Validity of 
Commands 15-1 

Sequence of Operations 15-1 
Acceptance of Double-Byte Character Set Data (MVS/XA Only) 15-2 
Using the Command Scan Service Routine (IKJSCAN) 15-3 
Command Name Syntax 15-4 

The Parameter List Structure Required by Command Scan 15-5 
The Command Scan Parameter List 15-5 
Flags Passed to Command Scan 15-6 
The Command Scan Output Area 1 5-6 
The Operation of the Command Scan Service Routine 1 5-7 
Results of the Command Scan 15-8 
Return Codes from Command Scan 1 5-9 
Using the Parse Service Routine (IKJPARS) 15-9 
Command Parameter Syntax 15-12 
Positional Parameters 15-12 
Keyword Parameters 15-29 
Using the Parse Macro Instructions to Define Command Syntax 15-30 
IKJPARM - Beginning the PCL and the PDL 15-31 
IKJPOSIT - Describing a Delimiter-Dependent Positional 

Parameter 15-32 
IKJTERM - Describing a Delimiter-Dependent Positional 

Parameter 1 5-36 
IKJOPER - Describing a Delimiter-Dependent Positional 

Parameter 15-40 
IKJRSVWD - Describing a Delimiter-Dependent Positional 

Parameter 1 5-44 
IKJIDENT - Describing a Non-Delimiter-Dependent Positional 

Parameter 15-46 
IKJKEYWD - Describing a Keyword Parameter 15-52 
IKJNAME - Listing the Keyword or Reserved Word Parameter 

Names 15-54 
IKJSUBF - Describing a Keyword Subfield 15-56 
IKJENDP - Ending the Parameter Control List 15-57 
IKJRLSA - Releasing Virtual Storage Allocated by Parse 15-58 
Passing Control to the Parse Service Routine 15-58 

The Parse Parameter List 15-59 
Formats of the PDEs Returned by the Parse Service Routine 15-60 
The PDL Header 15-60 
PDEs Created for Positional Parameters 15-61 
Effect of List and Range Options on PDE Formats 15-76 
The PDE Created for a Keyword Parameter 15-83 
Additional Facilities Provided by Parse 15-83 



Contents Xlll 



Translation to Uppercase 15-83 

Insertion of Default Values 1 5-84 

Passing Control to a Validity Checking Routine 15-84 

Insertion of Keywords 15-85 

Issuing Second Level Messages 1 5-86 

Prompting 15-86 
Examples of Using the Parse Service Routine 15-88 

Example 1 15-88 

Example 2 15-91 

Example 3 15-94 

Example 4 15-98 
Return Codes from the Parse Service Routine 15-101 

Chapter 16. Catalog Information Routine (IK JEHCIR) 16-1 
Return Codes from IKJEHCIR 16-3 
Return Codes from LOCATE 16-3 

Chapter 17. Default Service Routine (IKJEHDEF) 17-1 

Chapter 18. Testing a Newly- Written TMP or CP - The TEST Command 18-1 
When You Would Use TEST 18-3 

Testing a Currently Executing Program 18-3 

Testing a Program Not Currently Executing 18-4 
Addressing Restrictions 18-4 

Executing a Program under the Control of TEST 1 8-5 
Establishing and Removing Breakpoints within a Program 18-7 
Displaying Selected Areas of Storage 18-7 
Changing Instructions, Data Areas, or Register Contents 18-9 
Forcing Execution of Program Subroutines 18-10 
Using TEST after a Program ABEND 18-10 
Determining Data Set Information 18-11 

Appendix A. Notation for Defining Macro Instructions A-l 

Appendix B. Using VTAM Full-Screen Mode B-l 

Writing a Full-Screen Command Processor B-l 

(1) Set Full- Screen Mode On B-2 

(2) Give Control to the Command Processor B-3 

(3) Write to and Get Information from the Terminal B-3 

(4) Exiting and Reentering Full-Screen Mode B-4 

(5) Full-Screen Command Processor Termination B-5 
Full-Screen Protection Responsibilities of Attention Exit Routines B-5 
Examples of Full-Screen Command Processor Operation B-6 

Function of RESHOW in Full-Screen Message Processing B-7 
Function of INITIAL = YES when the First Message is Full Screen B-8 
Function of INITIAL = YES when the First Message is Non-Full Screen B-9 
Function of INITIAL = NO B- 1 

Index X-l 



xiv TSO/E Guide to Writing a TMP or a CP 



Figures 



2-1. 

2-2. 
2-3. 
2-4. 
2-5. 
2-6. 
2-7. 
3-1. 
3-2. 
3-3. 
3-4. 

4-1. 

5-1. 

5-2. 

5-3. 

5-4. 

6-1. 

6-2. 

6-3. 

6-4. 

6-5. 

7-1. 

7-2. 

7-3. 

8-1. 

8-2. 

9-1. 

9-2. 

9-3. 

9-4. 

9-5. 

10-1. 

10-2. 

10-3. 

10-4. 

10-5. 

10-6. 

10-7. 

10-8. 

10-9. 

10-10. 

10-11. 

10-12. 



A LOGON Procedure 2-2 

Requesting a Command 2-4 

The TSEVENT Macro Instruction Specifying PPMODE 2-5 

ABEND, ESTAI, ESTAE Relationship 2-6 

Parameters Passed to the Attention Exit Routine 2-10 

The Attention Exit Parameter List 2-11 

The Terminal Attention Interrupt Element 2-11 

Format of a HELP Data Set 3-12 

An Example of a User's SAMPLE Command Format 3-13 

An Example of a User's EXAMPLE Subcommand Format 3-13 

Coding Example - Including the SAMPLE Command and EXAMPLE 

Subcommand in the HELP Data Set 3-14 

MVS/XA Interface Rules for Macro Instructions 4-5 

TSO Service Routine 5-1 

Invoking an Authorized Command Using IKJEFTSR 5-3 

IKJEFTSR Return Codes 5-6 

IKJEFTSR Reason Codes 5-7 

Program Access to CLIST Variables 6-2 

Update or Create a CLIST Variable Value 6-4 

Update a CLIST Variable Value Only 6-6 

Return a CLIST Variable Value 6-9 

Return all Active CLIST Variables and their Values 6-12 

Control Block Interface between the TMP and CP 7-2 

The Command Processor Parameter List (CPPL) 7-3 

The CALLTSSR Macro Instruction 7-4 

The IKJTSMSG Macro Instruction 8-7 

An Example of an IKJTSMSG Macro Instruction 8-8 

The STAX Macro Instruction - List and Execute Forms 9-4 

Using Registers in the STAX Macro Instruction 9-6 

The STAX Parameter List 9-7 

The STAX Parameter List Extension for MVS/XA 9-7 



Coding Example - STAX Macro Instruction 
Control Blocks Passed to DAIR 10-3 
Format of the DAIR Parameter List (DAPL) 
DAIR Entry Codes and Their Functions 10- 
DAIR Parameter Block ~ Entry Code X'00' 
DAIR Parameter Block ~ Entry Code X'04' 
DAIR Parameter Block ~ Entry Code X'08' 
DAIR Parameter Block ~ Entry Code X'OC 
DAIR Parameter Block ~ Entry Code X'10' 
DAIR Parameter Block - Entry Code X'14' 
DAIR Parameter Block -- Entry Code X'18' 
DAIR Parameter Block -- Entry Code X'lC 
DAIR Parameter Block ~ Entry Code X'24' 



9-9 

10-4 
5 

10-6 
10-7 
10-8 

10-11 
10-11 
10-12 
10-13 

10-14 
10-15 



Figures XV 



10-13. DAIR Parameter Block -- Entry Code X'28' 10-17 

10-14. DAIR Parameter Block -- Entry Code X'2C 10-18 ( 

10-15. DAIR Parameter Block -- Entry Code X'30' 10-19 N 

10-16. DAIR Parameter Block - Entry Code X'34' 1 0-2 1 

10-17. DAIR Attribute Control Block (DAIRACB) 10-22 

11-1. BSAM/QSAM Macro Functions Under TSO 1 1-2 

12-1. The Input/Output Parameter List 12-2 

12-2. Control Block Interface Between the TMP and I/O Service 
Routine 12-3 

12-3. The List Form of the STACK Macro Instruction 12-5 

12-4. The Execute Form of the STACK Macro Instruction 12-8 

12-5. The STACK Parameter Block 12-13 

12-6. STACK Control Blocks: No In-Storage List 12-14 

12-7. Coding Example - STACK Specifying the Terminal as the Input 
Source 12-15 

12-8. The List Source Descriptor 12-16 

12-9. STACK Control Blocks: In-Storage List Specified 12-17 

12-10. Coding Example - STACK Specifying an In-Storage List as the Input 

Source 12-18 

12-11. The List Form of the GETLINE Macro Instruction 12-21 

12-12. The Execute Form of the GETLINE Macro Instruction 12-23 

12-13. The GETLINE Parameter Block 12-28 

12-14. Format of the GETLINE Input Buffer 12-29 

12-15. GETLINE Control Blocks - Input Line Returned 12-30 

12-16. Coding Example - Two Executions of GETLINE 12-31 

12-17. The List Form of the PUTLINE Macro Instruction 12-34 

12-18. The Execute Form of the PUTLINE Macro Instruction 12-38 

12-19. The PUTLINE Parameter Block 12-43 \ 

12-20. PUTLINE Single Line Data Format 12-44 

12-21. Coding Example - PUTLINE Single Line Data 12-45 

12-22. PUTLINE Multiline Data Format 12-46 

12-23. Coding Example - PUTLINE Multiline Data 12-47 

12-24. The Output Line Descriptor (OLD) 12-49 

12-25. Control Block Structures for PUTLINE Messages 12-50 

12-26. PUTLINE Functions and Message Types 12-51 

12-27. Coding Example - PUTLINE Text Insertion 12-53 

12-28. Coding Example - PUTLINE Second Level Informational 

Chaining 12-56 

12-29. The List Form of the PUTGET Macro Instruction 12-59 

12-30. The Execute Form of the PUTGET Macro Instruction 12-64 

12-31. The PUTGET Parameter Block 12-70 

12-32. The Output Line Descriptor (OLD) 12-72 

12-33. Control Block Structures for PUTGET Output Messages 12-73 

12-34. Format of the PUTGET Input Buffer 12-76 

12-35. PUTGET Control Block Structure - Input Line Returned 12-77 

12-36. Coding Example - PUTGET Multilevel PROMPT Message 12-78 

13-1. The TPUT Macro Instruction ~ Standard, Register, List, and Execute 
Forms 13-2 

13-2. The TPG Macro Instruction - Standard, List, and Execute 
Forms 13-8 

13-3. The TGET Macro Instruction — Standard, Register, List, and Execute 
Forms 13-10 

13-4. TPUT Parameter Registers 13-13 , 

13-5. TGET Parameter Registers 13-14 



XVI TSO/E Guide to Writing a TMP or a CP 



13-6. Parameter List Expansion for the Execute Form of TPUT 13-15 

13-7. Parameter List Expansion for the List Form of TPUT 13-15 

13-8. Parameter List Expansion for the Execute Form of TPG 13-16 

13-9. Parameter List Expansion for the List Form of TPG 13-16 

13-10. Parameter List Expansion for the Standard, List, and Execute Forms of 

TGET 13-17 

13-11. Coding Example: TPUT and TGET Macro Instructions Using the 

Default Values 13-18 

13-12. Coding Example: TPUT Macro Instruction Buffer Address and Buffer 

Length in Registers 13-19 

13-13. Coding Example: TGET Macro Instruction Register Format 13-20 

14-1. The GTDEVSIZ Macro Instruction 14-2 

14-2. The GTSIZE Macro Instruction 14-3 

14-3. The GTTERM Macro Instruction 14-3 

14-4. Parameter List Expansion for the List Form of GTTERM 14-4 

14-5. The RTAUTOPT Macro Instruction 14-5 

14-6. The SPAUTOPT Macro Instruction 14-5 

14-7. The ST ATTN Macro Instruction 14-6 

14-8. The STAUTOCP Macro Instruction 14-8 

14-9. The STAUTOLN Macro Instruction 14-9 

14-10. The STBREAK Macro Instruction 14-11 

14-11. The STCC Macro Instruction 14-13 

14-12. The STCLEAR Macro Instruction 14-14 

14-13. The STCOM Macro Instruction 14-15 

14-14. The STFSMODE Macro Instruction 14-16 

14-15. The STLINENO Macro Instruction 14-17 

14-16. The STSIZE Macro Instruction 14-18 

14-17. The STTIMEOU Macro Instruction 14-20 

14-18. The STTMPMD Macro Instruction 14-21 

14-19. The STTRAN Macro Instruction 14-22 

14-20. The TCLEARQ Macro Instruction 14-24 

15-1. The Parameter List Structure Passed to Command Scan 15-5 

15-2. The Command Scan Parameter List 15-6 

15-3. The Command Scan Output Area 15-6 

15-4. Character Types Recognized by Command Scan and Parse 15-8 

15-5. Return from Command Scan - CSOA and Command Buffer 
Settings 15-9 

15-6. A Command Processor Using the Parse Service Routine 15-10 

15-7. Delimiter-Dependent Parameters 15-13 

15-8. Example of 24-Bit Indirect Addressing 15-16 

15-9. Example of 31 -Bit Indirect Addressing 15-16 

15-10. An Indirect Address with Mixed Indirection Symbols 15-17 

15-11. An Address Expression with 24-Bit Indirect Addressing 15-18 

15-12. An Address Expression with Mixed Indirection Symbols 15-20 

15-13. The IKJPARM Macro Instruction 15-31 

15-14. The Parameter Control Entry Built by IKJPARM 15-31 

15-15. The IKJPOSIT Macro Instruction 15-32 

15-16. The Parameter Control Entry Built by IKJPOSIT 15-35 

15-17. The IKJTERM Macro Instruction 15-36 

15-18. The Parameter Control Entry Built by IKJTERM 15-39 

15-19. The IKJOPER Macro Instruction 15-41 

15-20. The Parameter Control Entry Built by IKJOPER 15-43 

15-21. The IKJRSVWD Macro Instruction 15-44 

15-22. The Parameter Control Entry Built by IKJRSVWD 15-46 



Figures XV11 



15-23. The IKJIDENT Macro Instruction 15-47 

1 5-24. The Parameter Control Entry Built by IKJIDENT 15-51 

15-25. The IKJKEYWD Macro Instruction 15-53 

15-26. The Parameter Control Entry Built by IKJKEYWD 15-53 

15-27. The IKJNAME Macro Instruction (when used with the IKJKEYWD 

Macro Instruction) 15-54 

15-28. The IKJNAME Macro Instruction (when used with the IKJRSVWD 

Macro Instruction) 15-55 

15-29. The Parameter Control Entry Built by IKJNAME 15-56 

15-30. The IKJSUBF Macro Instruction 15-57 

15-31. The Parameter Control Entry Built by IKJSUBF 15-57 

15-32. The IKJENDP Macro Instruction 15-57 

15-33. The Parameter Control Entry Built by IKJENDP 15-57 

15-34. The IKJRLSA Macro Instruction 15-58 

15-35. Control Flow between Command Processor and the Parse Service 

Routine 15-59 

15-36. The Parse Parameter List 15-60 

15-37. Series of PDEs Created for Mixed Sequence of Indirection 

Symbols 15-68 

15-38. A PDL Showing PDEs Describing a List 15-77 

15-39. A PDL Showing PDEs Describing a Range 15-78 

15-40. A PDL Showing PDEs Describing LIST and RANGE Options 15-79 

15-41. PDL - LIST and RANGE Acceptable, Single Parameter Entered 15-80 

15-42. PDL - LIST and RANGE Acceptable, Single Range Entered 15-80 

15-43. PDL - LIST and RANGE Acceptable, LIST Entered 15-81 

15-44. PDL - LIST and RANGE Acceptable, List of Ranges Entered 15-82 

15-45. Format of the Validity Check Parameter List 15-85 

15-46. Return Codes from a Validity Checking Routine 15-85 

15-47. Coding Example 1 - Using Parse Macros to Describe Command 

Parameter Syntax 15-89 

15-48. An IKJPARMD DSECT (Example 1) 15-90 

15-49. The IKJPARMD DSECT and the PDL (Example 1) 15-91 

15-50. Coding Example 2 - Using Parse Macros to Describe Parameter 

Syntax 15-92 

15-51. An IKJPARMD DSECT (Example 2) 15-92 

15-52. The IKJPARMD DSECT and the PDL (Example 2) 15-94 

15-53. Coding Example 3 - Using Parse Macros to Describe Parameter 

Syntax 15-95 

15-54. An IKJPARMD DSECT (Example 3) 15-95 

15-55. The IKJPARMD DSECT and the PDL (Example 3) 15-97 

15-56. Coding Example 4 - Using Parse Macros to Describe Parameter 

Syntax 15-98 

15-57. An IKJPARMD DSECT (Example 4) 15-99 

15-58. The IKJPARMD DSECT and PDL (Example 4) 15-100 

16-1. Catalog Information Routine Parameter List (CIRPARM) 16-1 

16-2. Data Returned from Valid CIROPT Values 16-2 

16-3. User Work Area for CIRPARM 16-2 

16-4. Volume Information Format 16-2 

18-1. The TEST Subcommands 18-2 

18-2. Issuing the TEST Command 18-6 

B-l. Macros Used to Write a Full-Screen Command Processor B-2 

B-2. Function of RESHOW in Full-Screen Message Processing B-7 

B-3. Function of INITIAL = YES when First Message is Full-Screen B-8 



XV111 TSO/E Guide to Writing a TMP or a CP 



B-4. Function of INITIAL = YES when First Message is 

Non-Full-Screen B-9 
B-5. Function of INITIAL = NO B-10 



Figures XIX 



XX TSO/E Guide to Writing a TMP or a CP 



Summary of Amendments 



Summary of Amendments 

for SC28-1 136-3 

for TSO Extensions Release 2.1 

This revision describes the changes in TSO Extensions Release 2.1 to allow 
command scan and parse to accept double-byte character set data. These changes 
apply only to an MVS/XA environment when the PTF for APAR OZ91711 is 
installed on your system. 

There are minor technical corrections and editorial changes throughout the book. 
Chapter 6, "Program Access to CLIST Variables," and Appendix B, "Using 
VTAM Full-Screen Mode," have been rewritten. 



Summary of Amendments 
for SC28-1 136-2 
as Updated December 7, 1984 
For TSO Extensions Release 2.1 

This edition supports TSO Extensions Release 2.1. The changes apply to the 
MVS/Extended Architecture environment only. TSO/E Release 2. 1 supports the 
following: 

• Increased virtual storage, which has most I/O service routines and 
miscellaneous service routines executing in 31 -bit addressing mode and 
accepting input above or below the 16-megabyte line. 

• The include control character in the HELP data set, which allows the 
insertion of additional help information into existing help members. 

Minor technical corrections and editorial changes are made throughout the book. 
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Summary of Amendments 
for SC28-1 136-1 
as Updated June 29, 1984 
For TSO Extensions Release 2 

This edition contains the changes in support of TSO Extensions Release 2. These 
changes consist of two new chapters: 

• "Invoking Other Programs with the TSO Service Routine" 

• "Program Access to CLIST Variables" 

This edition applies to TSO/E Release 2 running under either MVS/System 
Product Version 1 or MVS/System Product Version 2. The previous edition 
applies only to TSO/E Release 1 running under MVS/XA and can be ordered 
using temporary order number ST28-1136. 
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Chapter 1. Introduction 



TSO/E consists of many relatively small, functionally distinct modules of code. 
One major benefit of this modular construction is that the installation can add to 
or modify TSO/E to better suit the needs of its users. You can add to or replace 
IBM-supplied code with your own, and delete those functions of TSO/E which 
you do not require. 

TSO/E is composed of modules that communicate with the user and perform the 
work requested by him. Modifications to the control program should be made 
only by system programmers responsible for the proper functioning of TSO within 
MVS. Each installation can replace or modify the terminal monitor program 
(TMP), or any of the command processors. 

TSO/E also provides the user with the TSO Service Routine (IKJEFTSR), that 
allows a program to invoke a command processor (CP) or program by 
IKJEFTSR regardless of whether or not the invoked command processor or 
program runs authorized. 

If you choose to write your own terminal monitor program or a command 
processor, you can use the service routines, command processors, and macro 
instructions, supplied with TSO/E or modified to support TSO/E, to provide 
many of the functions required by a TMP or a command processor. 



The Terminal Monitor Program (TMP) and Command Processors 



The terminal monitor program is a problem program that accepts and interprets 
commands. The TMP also causes the appropriate command processor to be 
scheduled and executed. 

A terminal monitor program must be able to communicate with the user at the 
terminal, load and pass control to command processors, respond to abnormal 
terminations at its own task level or at lower levels, and respond to and process 
attention interruptions. 

When a user logs on to TSO/E, the user must either specify the name of a 
LOGON procedure by the LOGON command or accept that user's default 
procedure name from the user attribute data set (UADS). In either case, the 
program named in the EXEC statement of the LOGON procedure is attached 
during the logon as the terminal monitor program. The program named in the 
EXEC statement can be either the TMP supplied with TSO/E, one provided by 
the installation, or one you have written yourself. 
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Once the logon has completed, the terminal monitor program requests the user at 
the terminal to enter a command name. The IBM-supplied TMP writes a 
READY message to the terminal to indicate that a command should be entered. 
The TMP determines if the response entered is a command. If the response is a 
command, the TMP attaches the requested command processor (CP), and the 
command processor performs the computing functions requested by the user at 
the terminal. 

When writing your own command processors, keep in mind that you can add 
them to the IBM-supplied command library, concatenate your own command 
library to the one supplied by IBM, or replace the entire TSO/E command library 
with your own. 

Command processors (CPs) must be able to communicate with the user at the 
terminal, respond to abnormal terminations, and process attention interruptions. 
If required, command processors must be able to load and pass control to 
subcommand processors, as well as process abnormal terminations of 
subcommand processors. 



Basic Functions of Terminal Monitor Programs and Command 
Processors 

You can see from the preceding discussion that any terminal monitor program 
and any command processor must provide four basic functions: 

1. Both the TMP and command processors must be able to communicate with 
the user at the terminal. 

2. The TMP must be able to load and pass control to a command processor. If 
a command processor has subcommand processors, it must be able to load 
and pass control to them. 

3. Both the TMP and command processors must be able to intercept and 
investigate abnormal terminations. 

4. Both the TMP and command processors must be able to respond to and 
process attention interruptions entered from the terminal. 

You can provide each of these functions for a terminal monitor program or a 
command processor by using a service routine or a macro instruction provided 
with or modified to support TSO/E. 
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Communicating with the User 



There are three ways a program running under TSO/E can communicate with a 
user: 

1. The BSAM or QSAM access methods. 

2. The STACK, GETLINE, PUTLINE, and PUTGET I/O service routines. 
These routines are invoked by the STACK, GETLINE, PUTLINE, and 
PUTGET macro instructions respectively. They provide the following 
functions: 

STACK - The STACK service routine establishes and changes the source of 
input by adding elements to, or deleting elements from, an internally 
maintained input stack. The top element on the input stack determines the 
current source of input. 

GETLINE - The GETLINE service routine obtains and returns all input lines 
other than commands, subcommands, and responses to prompting messages. 
(A prompting message asks the user at the terminal to supply required 
information.) The GETLINE service routine returns these lines of input from 
the input source designated by the top element of the input stack. 

PUTLINE - The PUTLINE service routine formats output lines, writes them 
to the terminal, and chains second level messages to be written in response to 
a question mark from the terminal. 

PUTGET - The PUTGET service routine writes a message to the terminal 
and obtains a response from the terminal. A message written to the terminal 
that requires a response is called a conversational message. 

3. The TGET, TPUT, and TPG supervisor call. A supervisor call routine, SVC 
93, is invoked by the TGET, TPUT, and TPG macro instructions. TGET, 
TPUT, and TPG provide a route for I/O to a terminal. 

Each of these methods performs different functions and is thus suited for 
particular I/O situations. The programmer designing his own TMP or command 
processor must understand which of the I/O methods best provides the I/O 
support required in different programming situations. 



Passing Control to Command and Subcommand Processors 



A terminal monitor program must be able to recognize a command name entered 
into the system, load the requested command processor, and pass control to it. A 
command processor must be able to perform similar functions when a 
subcommand name is entered. 

Your TMP or command processor can use the command scan service routine to 
search the input line for a syntactically valid command name or subcommand 
name. The ATTACH macro instruction can then be issued to pass control to the 
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requested routines and to establish ESTAI exits. (See "Responding to Abnormal 
Terminations.") ^ 

When you write a command processor or subcommand processor, you can use the 
parse macro instructions to describe to the parse service routine the operands that 
may be entered with the command name. You can then use the parse service 
routine to determine which operands are present in the input buffer. The parse 
service routine compares the information you supplied in the parse macro 
instructions with the contents of the input buffer. This syntactical comparison 
indicates which operands are present in the input line. The parse service routine 
returns a list to the calling routine, indicating which operands were found in the 
buffer. These operands indicate to the processing routine the functions the user is 
requesting. 



Invoking Programs or Commands 



Another service that TSO/E provides is the ability for authorized TSO command 
processors or other authorized programs to run in an unauthorized environment. 
For additional information concerning this service see the TSO Service Routine 
chapter. 



Responding to Abnormal Terminations 



A programmer coding a routine to run under TSO/E should do all that is possible 
to keep that routine from causing an abnormal termination of a TSO/E user. If 
you write your own terminal monitor program or command processors, you 
should use the ESTAE or FESTAE macro instruction and the ESTAI operand on 
the ATTACH macro instruction to provide error handling exits. 

Use the ESTAE or FESTAE macro instruction to provide the address of an error 
handling routine to be given control if any routine at the same task level as the 
error handling routine begins to terminate abnormally. 

Use the ESTAI operand on the ATTACH macro instruction to provide the 
address of an error handling routine to be given control if a routine at a lower 
task level begins to terminate abnormally. 



Responding to Attention Interruptions 



A terminal monitor program and any command processor that accepts 
subcommands must be able to respond to an attention interruption entered from 
the terminal. TSO/E interprets an attention interruption as a signal that the user 
wants to halt current program execution, possibly to request a new command or 
subcommand. You must provide attention exits that can obtain a line of input 
from the terminal and respond to that input. 
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To build the control blocks and queues necessary for the system to recognize and 
schedule your attention handling routines, use the ST AX (specify terminal 
attention exit) service routine, which is invoked by the ST AX macro instruction. 



Other Functions Provided with TSO/E 



Aside from the four basic functions provided by a terminal monitor program or a 
command processor, other useful time sharing functions can be obtained using 
routines provided by IBM. 

Three of these functions are: 

1. The dynamici^allocation of data sets 

2. The immediate, on-line testing of a newly-written terminal monitor program 
or command processor 

3. Invoking programs or command processors without having to first determine 
if the command processor or program runs authorized. 

These three functions are provided through the dynamic allocation interface 
routine (DAIR), the TEST command processor, and the TSO Service Routine 
(IKJEFTSR) respectively. 



Dynamic Allocation of Data Sets 



You can invoke dynamic allocation using the dynamic allocation interface routine 
(DAIR) to: 

• Obtain the current status of a data set 

• Allocate a data set 

• Free a data set 

• Concatenate data sets 

• Remove data sets from a concatenation 

• Build a list of attributes (DCB parameters) to be assigned to data sets 

• Delete a list of attributes 

It is recommended, however, that you invoke dynamic allocation directly 
whenever possible (especially when writing new command processors) to take 
advantage of the additional functions available and to decrease system overhead. 
For a detailed description of these functions and how to invoke dynamic 
allocation directly, refer to System Programming Library: System Macros and 
Facilities. 

The DAIR interface, designed to invoke dynamic allocation for you, is 
maintained so that existing command processors do not have to be modified to 
invoke dynamic allocation directly. DAIR acts as a translator; it converts the 
DAIR parameter list it receives as input to a dynamic allocation parameter list, 
which it then passes to dynamic allocation. 



Chapter 1. Introduction 1-5 



Testing a TMP or a CP 



After you have coded a new TMP or CP, you will want to test it. Before you 
enter the program into TSO/E, you can use the TEST command to simulate the 
different execution paths you expect the program to follow successfully once you 
have entered it into TSO/E. 

The TEST command permits a terminal user to test an assembly language 
program. You test a program by issuing the TEST command and the various 
TEST subcommands that perform the following basic functions: 

• Execute the program being tested from its starting address or from any 
address within the program 

• Display selected areas of the program as it appears in virtual storage, or 
display the contents of any of the registers 

• Interrupt the program being tested at a specified location or locations 

• Change the contents of specified program locations in virtual storage or the 
contents of specific registers 

In addition to these basic debugging functions, you can use the TEST command 
to display various control blocks, program status words, or a virtual storage map 
of the program being tested. 



TSO Service Routine 



Program Interface to TSO/E Command Processors or Other Programs 



This interface enables unauthorized programs running under TSO/E to execute 
any TSO/E command processor or other program whether the command or 
program runs authorized or unauthorized. 

For example, an applications program written in PLI, COBOL, assembler, or any 
of the other IBM supported programming languages can use the interface, 
IKJEFTSR (alias name, TSOLNK), to invoke the ALLOCATE command 
processor to accomplish dynamic allocation of data sets. 

The TSO service routine can be invoked in both foreground and background 
TSO/E sessions. For additional information concerning this service see the TSO 
Service Routine chapter. 
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Chapter 2. The Terminal Monitor Program 



The terminal monitor program (TMP) is a program that provides an interface 
between the terminal user, command processors, and the TSO control program. 
TSO LOGON causes the system initiator to attach the program named on the 
EXEC statement of the user's LOGON cataloged procedure. This may be the 
IBM-supplied TMP or any user-supplied alternate. 

The user's LOGON procedure, which is specified on the LOGON command, 
defines the maximum number of concurrently allocated data sets allowed in a 
given TSO session. The LOGON procedure can contain: 

• DD statements that define data sets to be used during the TSO session 

• DD statements with the DYNAM parameter that increase by one the control 
limit for dynamically allocated resources held for reuse. The DYNAM 
parameter is supported to provide compatibility with older systems. Use of 
the DYNAMNBR keyword is recommended instead. 

• DYNAMNBR keyword on the EXEC statement. 

These statements set the control limit for the number of data sets that can be 
allocated to the user at any one time during the session. The formula for 
determining the control limit is: 

Control limit = # DD statements (with and without DYNAM) + the number supplied on the 
DYNAMNBR parameter of the EXEC statement. 

If a new dynamic allocation request exceeds the control limit, the allocation 
routines automatically attempt to deallocate enough data sets, marked 
"not-in-use", to meet the control limit. They deallocate the data sets that have 
been marked "not-in-use" for the longest time. If the request still exceeds the 
control limit, allocation fails and the user must explicitly deallocate an existing 
data set. 

Figure 2-1 shows an example of the EXEC statement in a user LOGON 
procedure. This procedure is equivalent to a LOGON procedure containing 10 
DD DYNAM statements and no DYNAMNBR operand. For a complete 
discussion of a LOGON procedure, see SPL: TSO/E User Exits and 
Modifications Volume 2. 
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Figure 2-1. A LOGON Procedure 



The terminal monitor program you use can be the TMP supplied with TSO, one 
provided by the installation, or one you have supplied yourself. If you choose to 
write your own terminal monitor program, use the TSO service routines and 
macro instructions described in this book to help you code the TMP and fit it 
into TSO. 

The TMP must be able to respond to the following four conditions: 

1 . Normal completion of a command processor or user program, and the 
requesting of another command 

2. An error causing termination of the TMP, a command processor, or a user 
program 

3. An attention interruption from the terminal, halting execution of the current 
program. 

4. A STOP operator command, forcing a LOGOFF for the user 

This section explains how to respond to these conditions. It describes in general 
terms how the IBM-supplied TMP functions, and how it fits together with the rest 
of TSO. For a more specific description of the IBM-supplied TMP, see Terminal 
Monitor Program and Service Routines Logic. 



Terminal Monitor Program Initialization 



In a LOGON procedure, the terminal monitor program (TMP) name must appear 
as the first operand of the PGM = keyword operand on the EXEC statement. 

When the TMP is attached: 

• Register 1 contains the address of the field containing the length and data of 
the EXEC parameter. The IBM-supplied TMP uses this PARM value as the 
first command requested. The first two bytes of the PARM value are on a 
halfword boundary and contain the length of the PARM value. (The length 
value does not include the two length bytes.) 

• Register 13 contains the address of the register save area. 

• Register 14 contains the return address of the LOGON/LOGOFF scheduler. 

• Register 1 5 contains the entry point address of the TMP. 
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The TMP sets up the tables and control blocks it requires, loads the TIME 
command processor, sets up the ESTAE and ESTAI exits to respond to abnormal 
terminations, sets up the attention exits, builds the command buffer, and 
initializes the input stack to point to the terminal. The TMP then uses the 
EXTRACT macro instruction to obtain the addresses of the STOP/MODIFY 
ECB and the protected step control block (PSCB) built by the LOGON/LOGOFF 
scheduler. 

The TMP determines whether it is running in a TSO or a batch environment by 
testing the time-sharing bit in the TCB. If the TMP is running in a batch 
environment, it will use the DATASET keyword while invoking the STACK 
service routine to cause GETLINE and PUTLINE to be directed to data sets. 
The TMP must also build the same control blocks that LOGON would have 
built. 

The IBM-supplied terminal monitor program attaches the command processor 
named in the EXEC statement PARM field. If no command was named as a 
PARM operand, the TMP issues a PUTGET macro instruction to obtain the first 
command. The TMP shares subpool 78 with the attached command processor 
but does not share subpool 0. The command processor, in turn, must share 
subpool 78 with any lower level tasks. 

The TMP should not pass in-line parameter lists to commands or TSO service 
routines. Subpool 251 should not be used for parameter lists. The command 
processor parameter list (CPPL), described later in this book, should be in 
subpool 1. You may use the IKJTMPWA macro to map the TMP work area. 

Requesting a Command 

Figure 2-2 summarizes the steps taken by a terminal monitor program to obtain a 
command, to pass control to the command processor, and to detach the command 
nrocessor when it has finished. 



processor when it has finished. 
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Figure 2-2. Requesting a Command 



Use the PUTGET service routine to request a command from the terminal. The 
PUTGET service routine first writes a line to the terminal to inform the user that 
another command is expected, then returns a line entered in response to the 
request, and places that line into a command buffer. 

Use the command scan service routine to determine whether the line of input is a 
syntactically valid command name. 



2-4 TSO/E Guide to Writing a TMP or a CP 



Use the ATTACH macro instruction (specifying an ESTAI exit routine) to pass 
control to the requested command processor. 

Your TMP must create any parameter lists expected by the command processor 
and pass them to the newly attached command processor. The IBM-supplied 
TMP passes the address of a command processor parameter list in register one. 
See the sections entitled "MVS/Extended Architecture Considerations" and 
"Processing Terminal Requests -- The TSO Service Routines" for more 
information about the interface between the TMP and command processors. 

When the command processor completes, the TMP releases it via a DETACH 
macro instruction, uses dynamic allocation to indicate that dynamically allocated 
data sets may be freed, and uses the PUTGET service routine to obtain another 
command. 

The TSEVENT macro facilitates the use of the generalized trace facility (GTF) to 
trace the attaching of a command processor by an installation-supplied terminal 
monitor program. The TSEVENT macro results in control being passed to a 
GTF hook located in the system resources manager (SRM) interface program. 

User written TMPs should issue the TSEVENT macro before attaching each 
command processor. 

Issue the TSEVENT macro instruction as follows: 

1 . Load register 1 with the first four characters of the command name being 
attached or released. 

2. Load register 15 with the last four characters of the command name. 

3. Code the TSEVENT macro instruction as shown in Figure 2-3. 



[label] 



TSEVENT 



PPMODE 



Figure 2-3. The TSEVENT Macro Instruction Specifying PPMODE 



Intercepting an ABEND 



The terminal monitor program must be able to recognize and respond to two 
basic types of ABEND situations: 

1 . An attached subtask (for example, a command processor) is terminating 
abnormally. 

2. The TMP itself or a program linked to by the TMP (for example, command 
scan) is terminating abnormally. 
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Intercepting a Subtask ABEND 



When a subtask of the terminal monitor program begins to terminate abnormally, 
the TMP ESTAI exit, specified by the TMP when it attached the subtask, receives 
control. The TMP ESTAI exit receives control under the TCB of the abending 
subtask. The subtask will already have performed its own ESTAE processing, if 
any was specified. Figure 2-4 shows the relationship between the ABEND, the 
ESTAE, and the ESTAI. For additional information about expanded recovery 
facilities available through ESTAI, refer to Supervisor Services and Macro 
Instructions. 
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Figure 2-4. ABEND, ESTAI, ESTAE Relationship 
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The TMP must inform the user at the terminal of the ABEND situation, and 
allow the user to enter another command. Use the PUTGET service routine, 
specifying the TERM operand, to inform the user of the ABEND and to return a 
line of input from the terminal. 

The terminal user has four options: 

1 . Allow the ABEND to continue by entering a null line (pressing the ENTER 
key). 

2. Terminate processing of the ABEND by entering a command name other 
than TEST or TIME. 

3. Request any second-level messages concerning the terminating program by 
entering a question mark. 

4. Place the terminating program under the control of the TEST command 
processor by entering the command name TEST. (See "Testing a 
Newly-Written TMP or CP ~ The TEST Command" later in this book.) 

Use the command scan service routine to determine what the user has entered at 
the terminal. 

If the user enters a null line, the TMP returns control to the ABEND routine, and 
the task is allowed to terminate abnormally. If the user enters a command name, 
other than TEST or TIME, the TMP processes the new command name after 
detaching the subtask. 

If the user enters a question mark, the PUTGET service routine causes the 
second-level informational message chain (if one exists) to be written to the 
terminal, again puts out the mode message, and returns the response from the 
terminal. 

When the TIME command is entered, the TMP links to the TIME command 
processor to obtain the time information. Upon completion of the TIME 
command, the user still has the above four options. 

If the user enters the TEST command, the TMP passes control to the TEST 
command processor via a SYNCH macro instruction. If any operands were 
entered on the TEST command, the TMP detaches all subtasks before invoking to 
the TEST command processor. If no operands were entered, the TMP does not 
detach any currently active subtasks. In this latter case, the user is requesting that 
the abnormally terminating task be run under the control of TEST. 



Intercepting a TMP Task ABEND 



When the TMP (or any program linked to by the TMP) causes an ABEND, the 
TMP ESTAE exit gains control. The TMP specifies its own ESTAE exit routine 
by issuing the ESTAE macro instruction. (See SPL: System Macros and 
Facilities for a discussion of the ESTAE macro instruction.) For a discussion of 
interface considerations for establishing ESTAE and ESTAI exit routines, refer to 
"ESTAE/ESTAI Exit Routines ~ Intercepting an ABEND" in the section on 
command processors in this manual. 
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Your TMP ESTAE exit routine can use the contents of the system diagnostic 
work area created by the ESTAE macro instruction to determine: 

• The type of error 

• The cause of the error 

• The PSW at the time of the ABEND 

• The last PSW before the program ABEND 

• The contents of the program registers 

If your TMP ESTAE exit routine cannot correct the problem, it should use the 
PUTLINE macro instruction to inform the user at the terminal that a task 
running under the TMP's TCB is terminating abnormally. Then the TMP 
ESTAE routine should do the following: 

• If a SYSABEND, SYSUDUMP, or SYSMDUMP data set was allocated 
during the user's session, take a dump of the user's region. 

• Clear the user's region. 

• Load a fresh copy of the TMP. 

• Begin processing as if the TMP had been invoked by the LOGON/LOGOFF 
scheduler. 

To obtain additional diagnostic information, your TMP ESTAE exit routine can 
issue the SDUMP macro to obtain an SVC dump. See SPL: Supervisor or SPL: 
System Macros and Facilities for information about how to use that macro. 

If the error persists and the TMP fails again, the ESTAE routine should pass 
control to the PUTLINE service routine to notify the user. A logoff should be 
forced by returning to the LOGON/LOGOFF scheduler. 

For additional information about expanded recovery facilities available through 
ESTAE and ESTAI, refer to Supervisor Services and Macro Instructions. 



Processing an Attention Interruption 



After having been attached, the TMP must set up its attention handling facilities. 
For this initialization process, you can use the ST AX macro instruction to pass 
the address of your attention handling routine to the system. 

For a discussion of interface considerations for attention exit routines, refer to 
"Specifying a Terminal Attention Exit - The ST AX Macro Instruction" later in 
this book. 

Several attention handling routines may be enqueued at any one time; that is, 
both the TMP and the currently active command processor may have issued 
ST AX macro instructions. For a description of how the user can request different 
levels of attention exits, see "Attention Interruption Handling -- The ST AX 
Service Routine" later in this book. 
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The attention handling routine you specify for the terminal monitor program is 
given control under any of the following conditions: 

1 . An attention interruption is entered from the terminal while the terminal 
monitor program is in control. 

2. An attention interruption is received from the terminal while a program 
(other than the terminal monitor program), that has not provided an 
attention handling routine, is in control. 

3. A program other than the terminal monitor program is in control. The 
program has provided an attention exit, but the user at the terminal has 
issued sufficient attention interruptions to reach the terminal monitor 
program's attention handling routine. As an example, if a command 
processor that has provided an attention handling routine is in control, and a 
user enters two successive attention interruptions from the terminal, the 
terminal monitor program's attention exit receives control. 

You can defer attention interruption processing with the DEFER operand of the 
STAX macro instruction. If you do use the DEFER option, attention 
interruptions are queued as they are received, and are not processed until you 
request that the DEFER option be removed. 



Parameters Received by Attention Handling Routines 



When your attention exit routine is entered, the registers contain the following 
information: 

Register Contents 

0,2-12 Irrelevant 

1 The address of the attention exit parameter list. 

13 Save area address. 

14 Return address. 

1 5 Entry point address of the attention handling routine. 

The attention exit parameter list pointed to by register one, contains the address 
of a terminal attention interruption element (TAIE). 

The parameter structure received by your attention exit routine is shown in 
Figure 2-5. 
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Entry from the STAX service routine 



Register 1 




Attention Exit 
Parameter List 



Attention Exit Routine 




Terminal Attention 
Interrupt Element 



Figure 2-5. Parameters Passed to the Attention Exit Routine 
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The Attention Exit Parameter List 



Figure 2-6 shows the format of the attention exit parameter list pointed to by 
register one when an attention exit routine receives control. 



Number 
of Bytes 


Field 


Contents or Meaning 


4 
4 

4 




The address of the terminal attention interrupt element (TAIE). 

The address of the input buffer you specified as the IBUF operand of 
the STAX macro instruction. Zero if you did not include the IBUF 
operand in the STAX macro instruction. 

The address of the user parameter information you specified as the 
USADDR operand of the STAX macro instruction. Zero if you did not 
include the USADDR operand in the STAX macro instruction. 



Figure 2-6. The Attention Exit Parameter List 



The Terminal Attention Interrupt Element (TAIE) 



The first word of the attention exit parameter list contains the address of an 
eighteen-word terminal attention interrupt element (TAIE). Figure 2-7 shows the 
format of the TAIE, which is mapped by the IKJTAIE macro. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 

I 

1 

4 

64 


TAIEMSGL 
TAIETGET 

TAIEIAD 
TAIERSAV 


The length in bytes of the message placed into the input buffer you 
specified as the IBUF operand on the STAX macro instruction. Zero if 
you did not code the IBUF operand in the STAX macro instruction. 

The return code from the TGET macro instruction issued to get the 
input line from the terminal. 

Reserved. 

Interruption address. The right half of the interrupted PSW. The 
address at which the program (or a previous attention exit) was 
interrupted. 

The contents of general registers, in the order - 1 5, of the interrupted 
program. 



Figure 2-7. The Terminal Attention Interrupt Element 

If you did not include the IBUF and the OBUF operands in the STAX macro 
instruction that set up the attention handling exit, use the PUTGET macro 
instruction, specifying the TERM operand, to send a mode message to the 
terminal identifying the program that was interrupted, and to obtain a line of 
input from the terminal. 

If you specify the OBUF operand on the STAX macro instruction without an 
IBUF operand, or with an IBUF length of 0, you can then use the PUTGET 
macro instruction, specifying the ATTN operand. This causes the PUTGET 
service routine to inhibit the writing of the mode message, since a message was 
already written to the terminal from the output buffer specified in the STAX 
macro instruction. The PUTGET service routine merely returns a logical line of 
input from the terminal. 

In either of the above cases, if the user enters a question mark, the PUTGET 
service routine automatically causes the second-level informational message chain 
(if one exists) to be written to the terminal, puts out the mode message again, and 
returns a line from the terminal. 
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If you used the IBUF operand on the ST AX macro instruction, note that no 

logical line processing or question mark processing is performed. If the user / 

returns a question mark, you will have to use the PUTLINE macro instruction to 

write the second-level informational message chain to the terminal. Then issue a 

PUTGET macro instruction, specifying the TERM operand, to write a mode 

message to the terminal and to return a line of input from the terminal. 

Use the command scan service routine to determine that the line of input is 
syntactically correct in the input buffer returned by the PUTGET service routine, 
or in the attention input buffer (pointed to by the second word of the attention 
exit parameter list). 

Special functions such as the TIME function should be performed immediately by 
the attention handling routine, and a new READY message should then be put 
out to the terminal, so that the terminal user may enter another command. Any 
other command should be passed to the TMP mainline routine for processing as if 
it were a newly entered command. 

Note that, with the exception of the TPUT ASID buffers for TCAM, the TGET, 
TPUT, and TPG buffers are flushed when an attention interruption is entered. If 
the user enters an attention interruption from the terminal and then enters a null 
line to continue processing, the contents, if any, of the TGET, TPUT, and TPG 
buffers are lost. 



Processing a STOP Command 



A STOP/MODIFY ECB is created by the time sharing system and can be 
obtained by your TMP by use of the EXTRACT macro instruction. During 
TMP processing, if a STOP command is indicated by a post to the STOP ECB, 
return to the LOGON/LOGOFF scheduler so that the user may be logged off the 
system. 
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Chapter 3. Command Processors 



A command processor is a problem program invoked by the TMP when a user at 
a terminal enters a command name. It may be link-edited into any library in the 
system link library list (LNKLSTxx) or SYS1.LPALIB. The command processor 
may be placed in a data set that is specified on the STEPLIB DD statement in a 
LOGON procedure. Execution should normally not be handled from a STEPLIB 
because of a decrease in performance during a system and TSO session. Refer to 
"Adding Commands to TSO" for a description of when a STEPLIB should be 
used. 

The internal logic of the IBM-supplied command processors is described in 
Command Processor Logic, Volumes I-IV. The command language used to 
request each of these command processors is described in the TSO/E Command 
Language Reference. 

If you choose to write your own command processors, you should be familiar 
with the service routines described in this book. 

This section discusses the relationships between the command processors and the 
rest of TSO, and provides guidelines for coding your own command processors. 

This section is divided into the following topics: 

• Adding Commands to TSO - Describes how to add a new command 
processor to TSO 

• Command Processor Coding Conventions - Describes normal interface 
conventions 

• Command Processor Use of the TSO Service Routines - Briefly discusses each 
of the TSO service routines and the situations in which they should be used 

• The ESTAE and ESTAI Exit Routines - Discusses the functions your error 
routines should provide 

• Attention Exit Routines - Discusses the need for attention handling exits and 
the functions those exits should perform 

• The HELP Data Set - Discusses the HELP data set, and the means of 
entering information into a HELP data set 
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Adding Commands to TSO 

There are three methods you can use to add a new command processor to TSO. 

1 . You can enter your command processor as a member of the partitioned data 
set SYS1.CMDLIB, via the linkage editor. 

2. You can create your own command library and concatenate it to the 

SYS l.CMDLIB data set. In this case, use the utility IEBUPDTE to create 
new statements in the link list (LNKLSTOO or LNKLSTxx) in 
SYS1.PARMLIB. 

3. Generally, unauthorized users can request that a LOGON procedure be 
created that specifies, on the STEPLIB DD statement, the name of the 
partitioned data set containing the command. 

Command Processor Coding Conventions 

The TMP uses standard linkage conventions in passing control to a command 
processor. The command processor parameter list (CPPL) is the input parameter 
list to all command processors. For more information on the CPPL, see the 
section called "Interfacing with the TSO Service Routines" later in this book. 

Command processors should contain logic that issues error messages. These 
messages should handle all error codes, expected or unexpected, from any routine 
or SVC they invoke. Whenever possible, generalized routines such as DAIRFAIL 
should be used. Use of these routines allows the issuance of meaningful error 
messages for return codes. 

When returning control to the TMP, the command processor should use standard 
linkage and set a return code in general register 15. Command procedures 
(CLISTs) may then check this code for the following conventions: 

- normal execution 

12 - termination error during execution (no error exists if a command processor is able to obtain 
required information by prompting) 

Command Processor Use of the TSO Service Routines 

Use the IBM-provided service routines described in this manual when coding your 
own command processors. Read the sections on the various service routines, 
macro instructions, and "Interfacing with the TSO Service Routines" for an 
understanding of the services they perform and how to use them. The following 
topics provide information on when to use each of the service routines. 

Note: "MVS/Extended Architecture Considerations" lists the linkage attributes 
for the TSO service routines. Additional descriptions of considerations caused by 
31 -bit addressing are provided in the sections describing the routines and macros. 
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STACK Service Routine 



Use the STACK service routine to change the source of input by adding an 
element to the input stack or to reset the input stack to the terminal element 
originally specified by the terminal monitor program. 

A command processor should issue the STACK macro instruction in the 
following circumstances: 

1 . Your command processor has created a series of commands to be executed 
after the command processor terminates. The command processor should 
build an in-storage list containing the commands to be executed and issue the 
STACK macro instruction to place a pointer to the list on the input stack. 

2. You may want to pass data from one of your command processors to another 
command processor. This data may be passed in storage via the input stack. 
Issue the STACK macro instruction to place a pointer to the in-storage data 
on the input stack. 

3. Your command processor performs functions similar to those performed by 
the IBM-supplied EXEC command (that is, it executes a command 
procedure). Your command processor should issue the STACK macro 
instruction to place a pointer on the input stack to the command procedure to 
be executed. 

4. Whenever one of your command processors, terminates with an error 
condition, its error handling routine should issue the STACK macro 
instruction to clear the input stack, before returning control to the TMP. The 
input stack must be cleared or command procedure (CLIST) processing will 
not be handled correctly. Commands such as DELETE and FREE do not 
flush the stack if the module requested was not found. 



Catalog Information Routine 



The catalog information routine (IKJEHCIR) retrieves information from the 
system catalog. This information may include a data set name, index name, 
control volume address, or volume ID. The information may be requested from a 
specific user catalog. If you do not specify a specific catalog, IKJEHCIR searches 
the system default catalog. An entry code indicates what kind of information is 
being requested. 

Use the CALL, CALLTSSR, or LINK macro instruction to invoke the catalog 
information routine. 

Note: For additional information concerning the catalog information routine, see 
"Catalog Information Routine (IKJEHCIR)" later in this book. 
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Default Service Routine 



The default service routine (IKJEHDEF) constructs a fully-qualified data set 
name when the calling routine provides a partially-qualified data set name. A 
fully-qualified data set name has three fields: a user ID, a data set name, and a 
descriptive qualifier. 

Use the CALL, CALLTSSR or LINK macro instruction to invoke the default 
service routine. At entry, general register 1 must point to the default parameter 
list (DFPL). IKJEHDEF then invokes the catalog information routine 
(IKJEHCIR) to search the system catalog for the required qualifiers. When the 
search argument is satisfied, the default service routine returns to the calling 
control program. All of the general registers are restored except for register 15 
which contains the return code. 

Note: For additional information concerning the default service routine, see 
Terminal Monitor Program and Service Routines Logic. 



GETLINE Service Routine 



Your command processors should use the GETLINE service routine to obtain 
data. The buffer returned by GETLINE is in subpool 1, and is owned by your 
command processor. For efficient execution, issue FREEMAIN macro 
instructions within each command processor, or within each subtask created by 
the command processor, to free the GETLINE buffers it obtains. 



PUTLINE Service Routine 



Your command processors should use the PUTLINE service routine to write 
informational messages or data to the terminal and to chain second level 
informational messages. PUTLINE writes the output lines to the terminal 
regardless of the source of input. TPUT should not be used under these 
circumstances. The GNRLFAIL service routine should be used to issue 
meaningful error messages for return codes from PUTLINE. 



PUTGET Service Routine 



Your command processors should use the PUTGET service routine for prompting 
and for subcommand requests. Use the operands on the PUTGET macro 
instruction to specify logical line processing with editing and the WAIT option. 

If the user enters a question mark in response to a message issued with a 
PUTGET macro instruction, the PUTGET service routine displays the second 
level messages chained by previous PUTLINE macro instructions. If the user 
responds with a subcommand name, the second level messages are deleted and the 
storage they occupied is freed. See "PUTGET Processing" for exceptions to this 
usual method of processing. 

As with the GETLINE service routine, the buffers returned by the PUTGET 
service routine belong to, and should be freed by, the command processor. 
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IKJEFF02 Message Issuer Service Routine 



If you make numerous insertions into messages, you should use this service 
routine instead of PUTLINE and PUTGET. Also, when you use IKJEFF02, all 
of your messages can be placed in a single GSECT or a single module. 



DAIR Service Routine 



You may use the DAIR service routine to obtain information about a data set 
and, if necessary, to invoke dynamic allocation routines to perform the requested 
function. However, additional functions are available if you invoke dynamic 
allocation directly. Another drawback to using DAIR is that it increases system 
overhead. For a discussion of how to invoke dynamic allocation directly, refer to 
SPL: System Macros and Facilities. 

If you are going to use DAIR, you should read the section called "Dynamic 
Allocation of Data Sets - The Dynamic Allocation Interface Routine (DAIR)" 
later in this book and adhere to the following guidelines: 

• Command processors should allocate data sets by DSNAME and use the 
DDNAMES returned by DAIR to open the data sets. If necessary, command 
processors should pass the DD names on to any subcommands or problem 
programs running under them, 

• Command processors should allow DAIR. the default service routine, or the 
parse service routine to prefix an identifier on the data set name so the 
PROFILE command's PREFIX and NOPREFIX options are automatically 
supported. You can use the default service routine to add any data set suffix 
that exists for the data set. (The default service routine is documented in 
Terminal Monitor Program and Service Routines Logic.) 

• Whenever the user specifies a password for a data set, the command processor 
should send the password to DAIR when allocation is requested. 

• Command processors should normally invoke DAIR to free all data sets at 
termination so other TSO users or submitted jobs can have full use of the 
data sets. 

• Before detaching terminated subcommands, command processors that accept 
subcommands should use DAIR to free any data sets allocated by the 
subcommands. 

• Command processors should use the DAIRFAIL service routine to issue 
meaningful error messages for non-zero return codes from DAIR. 



Command Scan Service Routine 



Your command processors should use the command scan service routine to scan 
for valid subcommand names. The option of checking the remainder of the input 
line for non-separator characters should be requested. If no additional significant 
characters are found in the line, the command processor subroutine need not 
invoke the parse service routine to scan the command operands because none are 
present. 
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Parse Service Routine 



Your command processors and subcommand processors should use the parse 
service routine to scan the operands entered with the command or subcommand 
name. The parse service routine returns a parameter descriptor list to the calling 
routine. The parameter descriptor list describes the operands found in the 
command buffer. 

In the parse macro instructions that define command syntax, command processors 
and subcommand processors can indicate to the parse service routine that validity 
checking exits be taken on certain types of operands. Because the parse service 
routine checks the operands only for syntax errors, you should indicate in the 
parse macros that validity checking routines be entered whenever a logical, rather 
than a syntactical, error might occur. 

The GNRLFAIL service routine should be used to issue meaningful error 
messages for non-zero return codes from the parse service routine. 

When the parse service routine prompts the user to enter a required operand, or 
to reenter a syntactically incorrect operand, the user may type in question marks 
to receive the second level messages associated with the operand. 



Prompt Mode HELP Function 



Once the second level messages are exhausted during a prompting sequence, if the 
user enters another question mark, parse processing determines whether it can 
generate a valid HELP command to provide the user with additional information. 

If the ECTNOQPR bit in the environment control table (ECT) is zero, then the 
prompt mode HELP function is active and parse processing generates a HELP 
command on the user's behalf. Parse processing ensures that only one HELP 
command is issued during a prompting sequence for a given operand. If the user 
enters another question mark after viewing the online usage information, the NO 
INFORMATION AVAILABLE message is issued. 

The TMP sets the ECTNOQPR bit to zero before attaching a primary command, 
except the TEST and LOGON commands for which the function is not available. 
Parse sets ECTNOQPR to one before it returns control to the command 
processor. Consequently, the prompt mode HELP function is not active during 
subsequent invocations of parse within the domain of the command, nor for any 
subcommands attached by the command processor. If your command processor 
does not want the prompt mode HELP function to be active for the entire 
domain of the command, it should set the ECTNOQPR bit to one prior to 
invoking parse for the first time. 

If your command processor accepts subcommands and wants the prompt mode 
HELP function to be available for a subcommand, it should set ECTNOQPR to 
one before attaching the subcommand. In this case, the command processor 
should ensure that the ECTPCMD and ECTSCMD fields -in the ECT contain the 
primary command name and the secondary command name respectively. 
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The prompt mode HELP function is active for all keyword operands of all 
commands (except the TEST and LOGON commands), including user-written 
commands. It is also active for the positional parameters of the following 
commands: ATTRIB, CALL, CANCEL, EDIT, EXEC, HELP, OUTPUT, 
RUN, and SEND. If you want to make this function available for the positional 
operands of other commands, as well as for the positional operands of 
user-written subcommands for which the prompt mode HELP function is enabled, 
you or your system programmer must update their corresponding HELP members 
as described in "Writing HELP Members" and "Updating Existing HELP 
Members" later in this section. 

Note: The prompt mode HELP function is not supported during LOGON 
processing. LOGON pre-prompt exit routines should not make the function 
active. 



ESTAE/ESTAI Exit Routine - Intercepting an ABEND 



Linkage Considerations 



Use the ESTAE and ESTAI exits in your command processors, if they are needed, 
to keep the system operable if abnormal termination occurs. ESTAE/ESTAI exits 
should be used in such a way that the command processor gets control if a 
subcommand abnormally terminates. If you issue an ESTAE, issue it as early as 
possible in your command processor. Any ESTAE should be issued before any 
ST AX. ESTAE provides the command processor with the ability to intercept an 
ABEND so that cleanup, bypass, and if possible, execution retry can be 
accomplished. (See SPL: System Macros and Facilities for a discussion of the 
ESTAE macro instruction. See Supervisor Services and Macro Instructions for a 
discussion of the ESTAI operand of the ATTACH macro instruction and for 
information about ESTAE and ESTAI exit routines.) 



Programs may issue the ESTAE and FESTAE macros, as well as the ATTACH 
macro with the ESTAI operand, in either 24- or 31 -bit addressing mode. The 
ESTAE, FESTAE, and ESTAI exit and recovery routines receive control in the 
same addressing mode in which the ESTAE, FESTAE, and ATTACH macros are 
issued. When the macros are issued in 31 -bit addressing mode, ESTAE, 
FESTAE, and ESTAI routines may reside above the 16-megabyte virtual storage 
line. 

The ESTAE, FESTAE, and ATTACH macros are downward incompatible. The 
MVS/Extended Architecture versions of these macros do not execute properly in 
MVS/370. For an explanation of how to select the desired macro level, see SPL: 
System Macros and Facilities. 

While not recommended, the STAE macro and the STAI operand of ATTACH 
may be used to provide error handling exits. However, programs executing in 
31 -bit addressing should not establish STAE or STAI recovery exits. 
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Command Processor Functions that Rely on Exit Routine Support 

The following types of command processors should use ESTAE exit routines: 

• All command processors that process subcommands 

• All command processors that request system resources that are not freed by 
ABEND or DETACH 

• Command processors that process lists, to allow processing of other elements 
in the list if a failure occurs while processing one element in the list 

Command processors that attach subcommands should also provide an ESTAI 
exit to intercept abnormally terminating subcommand processors. 

Simple command or subcommand processors should not issue an ESTAE or an 
ESTAI if the terminal monitor program or calling command processor ESTAI 
exits provide adequate processing. 

Guidelines for ESTAE and ESTAI Exit Routines 

ESTAE and ESTAI exit routines should observe the following guidelines: 

1 . The error handling exit routine should issue a diagnostic error message of the 
form: 

1st level i command-name ) ENDED DUE TO ERROR + 
\ subcommand-name I 

2nd level COMPLETION CODE IS xxxx 

The name supplied in the first level message is obtained from the environment 
control table, and the code supplied in the second level message is the 
completion code passed to the ESTAE or ESTAI exit from ABEND. The 
GNRLFAIL service routine may be used to issue the diagnostic error 
message, although it requires additional storage space (see guideline number 
4). 

The routine should issue these messages so that the original cause of 
abnormal termination is recorded should the error handling exit routine itself 
terminate abnormally before diagnosing the error. 

When an ABEND is intercepted, the command processor ESTAE exit routine 
should determine whether retry is to be attempted. If so, the exit routine 
should issue the diagnostic message and return, indicating via a return code 
that an ESTAE retry routine is available. If a retry is not to be attempted, 
the exit routine should return, indicating via a return code that no retry is to 
be attempted. The TMP ESTAI exit routine will issue the diagnostic 
message. (For a description of the return codes and their meanings, see 
Supervisor Services and Macro Instructions.) 
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2. The ESTAE or ESTAI routine that receives control from ABEND should 
perform all necessary steps to provide system cleanup. This cleanup should 
be performed in the ESTAE exit routine rather than in the ESTAE retry 
routine because DETACH with the ESTAE = YES operand does not allow 
the subtask to retry from an ESTAE/ESTAI exit. (The TMP issues 
DETACH with ESTAE = YES when a command processor has been 
interrupted with an attention.) 

3. The error handling exit routine should attempt to retry program execution 
when possible. If the command processor can circumvent or correct the 
condition that caused the error, the error handling routine should attempt to 
do so. In other cases, however, RETRY has no function and the command 
processor ESTAE exit should not specify the RETRY option. 

4. Storage might not be available when the ESTAE or ESTAI routine receives 
control. Any storage the routine requires should be acquired before it 
receives control, and be passed to it. 



Attention Exit Routines 



An attention exit routine should be provided by any command processor that 
accepts subcommands. Use the ST AX macro instruction to specify the address of 
your attention handling routine. See "Attention Interruption Handling - The 
ST AX Service Routine" for a complete discussion of the STAX macro instruction. 
Simple command processors should not issue a STAX if the TMP or the calling 
command processor STAX exits provide adequate processing. 

If you did not include the IBUF and the OBUF operands in the STAX macro 
instruction that set up the attention handling exit, use the PUTGET macro 
instruction, specifying the TERM operand, to send a mode message to the 
terminal identifying the program that was interrupted, and to obtain a line of 
input from the terminal. 

If you specify the OBUF operand on the STAX macro instruction without an 
IBUF operand, or with an IBUF length of 0, you can then use the PUTGET 
macro instruction, specifying the ATTN operand. This causes the PUTGET 
service routine to inhibit the writing of the mode messages, since a message was 
already written to the terminal from the output buffer specified in the STAX 
macro instruction. The PUTGET service routine merely returns a logical line of 
input from the terminal. 

In either of the above cases, if the user enters a question mark, the PUTGET 
service routine automatically causes the second level informational message chain 
(if one exists) to be written to the terminal, puts out the mode message again, and 
returns a line from the terminal. 

If you used the IBUF operand on the STAX macro instruction note that no 
logical line processing or question mark processing is performed. If the user 
returns a question mark, you will have to use the PUTLINE macro instruction to 
write the second level informational message chain to the terminal. Then issue a 
PUTGET macro instruction, specifying the TERM operand, to write a mode 
message to the terminal and to return a line of input from the terminal. 



Chapter 3. Command Processors 3-9 



Whether you use the IBUF operand on the ST AX macro instruction or the 
PUTGET macro instruction to return a line from the terminal, you can use the 
command scan service routine to determine what the user has entered. 

If the user enters a null line, the attention handling routine should return to the 
point of interruption. Note that, with the exception of the TPUT ASID buffers 
for TCAM, the TGET, TPG, and TPUT buffers are flushed during attention 
interruption processing. If any data was present in these buffers, it is lost. 

If a new command or subcommand is entered, the attention handling routine 
should: 

• Post the command processor's event control block to cause active service 
routines to return to the command processor. 

• Exit. 

• Reset the input stack in the command processor mainline. (A stack flush in 
an attention routine may cause severe errors.) 



The HELP Data Set 



A terminal user can enter the HELP command to retrieve information about 
commands or subcommands. This information is stored in a data set labeled 
SYS1.HELP (the HELP data set). If you add command processors to TSO, you 
should either add HELP information to the SYS1.HELP data set, or to a private 
HELP data set. 



Attributes of SYS1.HELP 



SYS 1. HELP is a cataloged, partitioned data set consisting of one member named 
COMMANDS and individual members for each command in the system. The 
COMMANDS member contains a list of the commands available to the user, and 
a brief description of each. The individual members for each command are 
named with the command name, and contain more specific information about the 
command and its subcommands. The HELP information contained within any 
member of the HELP data set consists of punch-card images. The logical record 
length is therefore 80 characters. 



Format of HELP Members 



Each of the HELP members, other than the COMMANDS member, is divided 
into the following subgroups, each of which can be displayed at the terminal: 

• A subcommand list - This appears only if the command has subcommands. 

• Functional description - This provides a brief description of the function of 
the command or subcommand. 

• Syntax - This describes the syntax of the command or subcommand. 
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• Message identifier description - This provides information pertaining to 
messages issued by the command or its subcommand. 

• Operand description - This provides information on the command operands. 
It includes individual sections containing brief descriptions of each positional 
operand, and of each keyword and its parameters. 



Private HELP Data Sets 



You may concatenate your data set to the SYS 1. HELP data set (or vice versa). 
Concatenated data sets need not have the same attributes as the SYS1.HELP data 
set, but the first concatenated data set must have the largest block size of the 
concatenated data sets, and it must not specify a fixed block size. 

Concatenated data sets are searched in the order of concatenation. If 
SYS1.HELP and a private HELP data set have been concatenated, the first 
COMMANDS member encountered by the HELP processor is used as the list of 
available commands. Thus, if you concatenate your own HELP data set to 
SYS1.HELP, you should make additions to the COMMANDS member of 
SYS 1. HELP. 

Private HELP data sets must be allocated with file name SYSHELP, either in the 
LOGON procedure or on an ALLOCATE command. When data sets are 
concatenated, the file name SYSHELP is required. If only SYS1.HELP is 
required, the file name SYSHELP would not have to be allocated. (See the 
DAIR entry code X'24' later in this book.) 



Updating SYS1.HELP 



Writing HELP Members 



Use the IEBUPDTE utility program or the EDIT command to update 
SYS 1. HELP. SYS 1. HELP is a system data set, so it will generally require 
operator intervention when it is updated. 



To add a new member to a data set named PRIVATE.HELP using the EDIT 
command, enter: 

edit 'private .help (mbr name) ' data new 
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Use the information described in Figure 3-1 when you add to SYS 1. HELP or set 
up your own HELP data set. The control characters, beginning in card column 1 , 
divide the data set into the subgroups previously described, and thereby permit 
the HELP command processor to select message text according to the operands 
supplied on the HELP command. (See TSO/E Command Language Reference for 
a discussion of the HELP command.) 



Control Character 


Purpose of Data Card 


)S 


This card indicates that a list of commands or subcommands follows. 


)F 


This card indicates that the functional discussion of the command or 
subcommand follows. 


)X 


This card indicates that the syntax description of the command or 
subcommand follows. 


)M 


This card indicates that message ID information follows. The information is 
only printed by the HELP command when the MSGID keyword is specified. 


)I membername 


In MVS/XA, this card includes additional help information in the specified 
member. The include control character, )I, can appear anywhere within a 
data set member. If the help information you plan to add is not available 
yet, you can specify the control character and later add the information. No 
error messages are issued. 




The member name can be up to eight characters in length. There must be at 
least one blank before and after the member name. 


))messageid 


This card indicates that information follows describing the named messageid. 
One of these control cards should be present for each message issued by the 
command. Each card contains the identifier of the message it describes. 
Message IDs can be any length and the first character must be alphabetic. 


)o 


This card indicates that the command operands and their descriptions 
follow. Positional operands must follow immediately after the )0 control 
card and before the ))keyword control cards. 


)P 


This card indicates that a positional operand description follows. One of 
these control cards is required for each positional operand within the 
command. Each card contains the name of the positional operand it 
describes. 


))keyword 


This card indicates that information follows describing the named keyword. 
One of these control cards must be present for each keyword operand within 
the command. Each card contains the name of the keyword it describes. 


= subcommandname 


This card indicates that information follows concerning the subcommand 
named after the equal sign. One of these cards is required for each 
subcommand accepted by the command being described. Note that this card 
merely names the subcommand; it does not describe it. Describe the 
subcommand in the same manner you would describe a command. 




If the subcommand has an alias name, you may include the alias name on 
the control card, i.e. = subcommandname = subcommandalias. Note that 
no blanks may appear between the subcommand and the alias. 



Figure 3-1. Format of a HELP Data Set 
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All data cards, except the = subcommandname card, can contain additional 
information. If you include additional information on the cards, the control 
characters )S, )F, )X, )I, )0, and )P must be followed by at least one blank, and 
the control character ))keyword by at least one blank or a left parenthesis. Any 
information after the membername field on the include, )I, data card is treated as 
a comment. Use the left parenthesis when the keyword you are describing is 
followed by operands enclosed in parentheses. 

The only restrictions on data cards are that columns 72-80 are reserved for 
sequence numbers, and column one must contain a right parenthesis, an equal 
sign, or a blank. The sequence numbers are not printed when the HELP 
command is executed. 

For example, information concerning a user's SAMPLE command, shown in 
Figure 3-2, could be formatted for entry into the HELP data set (or your own 
private help data set). 



SAMPLE 



positl [ , (posit2) ] [KEYWD1[ (p_osit3,posit4) 



Figure 3-2. An Example of a User's SAMPLE Command Format 

The SAMPLE command has one subcommand, the EXAMPLE subcommand (see 
Figure 3-3). Both the command and the subcommand can issue messages 
IKJXX110I and IKJXX111I. 



EXAMPLE 


posit 10, posit 11 


KEYWDlOj 
KEYWD11 
KEYWD12] 


[KEYWDl3(positl2) ] 



Figure 3-3. An Example of a User's EXAMPLE Subcommand Format 

Figure 3-3 shows data cards that would present and format information about the 
SAMPLE command and EXAMPLE subcommand for inclusion in the HELP 
data set. 
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JS THE SAMPLE COMMAND HAS THE r?.L I OW/ V$ SUBCO^^A^OS : 


EXAMPLE 


)F PV*C7/0*4L P&SCR/PT/O* OP THE SAMPLE COMMAND'. 


THE SAMPLE COMMAND /S A P/CT/T/O'SS COfrtoAVPl 


NO COMtoAH.D PROCESSOR EX/S7S W/TH 7H/S NAVE. 


THE SAMPLE COMMAND /S USED HEtELY 70 .DESCR/BE 


7HE Ft/VCT/ONS OP THE HELP OAT A SET CONTROL CARDS . 


)X THE SAMPLE COMHAV.O HAS THE FOLLOW/NG SYNTAX: 


PESCR/.3E THE SYNTAX 0* THE SAMPLE COMMAMO 


H£&£. _ __ 


U Hl&MUz xvtLUoe *di%txmal untax 'meo&h'Ulo* ?Q& tW 


SHnPLZ LQtiJWIb E'Aon HE LVlLLLAtZO. ttlLP <!£%&& 


;m the sample command ISSUES THE FOLLOWING MESSAGES: 


))l KJXX110I DESCRIBE THE MESSAGE IKJXX110/ HERE. 


))/KJXXf 1 7 1 DESCRIBE THE MESSAGE /KJXXtff/ HERE. 


)0 7HE SAMPLE COMHAHP HAS TWE foL-LW/VG P0S< T/ ONAL 


OPERANDS'. 


)P POS/Tt PESCR/BEj /T HERE, 


)P POS/TZ DESCR/8E /7 HERE* 


))KEY»D1 PESCR/BE THE kEY<rOPO } KEYfrDf HERE', /VCLoDE A 


OESCR/ PTJ ON OP _J_ 


P0S/T3 AND 


POS/T? 


'EXAMPLE 


)F cUNCTf ONAl PESCR/PT/ON OP THE EXAMPLE SV&CObffrAV.D: 


THE EXAMPLE SUBCOMMAND AS A P/Cr/T/ OUS 


SUBCOMMAHD . 


)X T^E EXAMPLE SUBCOMMAND MAS ■ r.HE FOLLOW'NG SYWTAXi 


.DESCRIBE THE SrNT\AX o* 7HE EXV/fOLEl S^BtoMfoAsWD 


HEWE 


JO THE EXAMPLE SV.B\COMtoAN.P HAS THE FOLLOW/ NG POS/T/ONAL 


OPERANDS: 


)P POS/Tftf DESCR/3\E /T HERE. 


)P POS/Tff .9ESC*?/8£ /7 HE&E. 


))KPY*Dt0 PESCR/BE AVE *EYH<0#D , KEY<vDt0 HERE. 


))K&YWD\fi Of SCR/ BE THE <£YVO\RV>, KEYWD/t H.cRE . 


) M^YWPfZ DESCRABE' THE] .KEYWORD, t,EY¥D1Z HERE- 


))«zww_3 (pos/tT^i 


PSESCR/SE THE kEYH&RD^ XEfrtyPJI^ AND THE 


POS/T/o\vAl- OPEfAA/p. POS/T1Z. HERE 



Figure 3-4. Coding Example - Including the SAMPLE Command and EXAMPLE Subcommand in the HELP Data 
Set 

If you are writing a HELP member for a user-written command, and the 
command processor wants the prompt mode HELP function to be available for 
its positional parameters and/or for those of one or more of its subcommands, do 
the following. Enter the positional parameter control character, )P, on the first 
line of each positional parameter description for the command and/or 
subcommand(s). (See "Prompt Mode HELP Function" earlier in this section.) If 
no description exists for a positional parameter, you should also supply the name 
of the positional parameter along with the information you would like displayed 
when the user requests information about the parameter. If a description exists, 
you may wish to modify it so that is does not repeat information provided by the 
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messages. This suggestion also applies to the other descriptions in the HELP 
members. Keep in mind, though, that the user can request help when not 
responding to prompt mode messages. (See "Updating Existing HELP Members" 
below for an example of how to update a HELP member for a command's 
positional parameters.) 

Note: If you insert a )P for only some of the positional parameters for a given 
command or for a given subcommand, unpredictable results may occur when 
parse processing issues a HELP command for one of its positional parameters. 

Updating Existing HELP Members 

For various reasons, you may wish to update existing HELP members. 

To make the prompt mode HELP function available for a command's positional 
parameters, assuming it has positional parameters, update the HELP member for 
the command in the following manner. (See "Prompt Mode HELP Function" 
earlier in this section for a description of this function and a list of the commands 
for which the function is automatically provided.) Starting in column one of the 
first line of each positional parameter description for the command, enter the 
positional parameter control character, )P. The prompt mode HELP function 
may also be active for one or more of a command's subcommands. For a 
subcommand for which this function is active, you should also insert a )P for each 
of its positional parameter descriptions in the HELP member. (See Figure 3-4.) 

If no description exists for a positional parameter, you should also supply the 
name of the positional parameter along with the information you would like 
displayed when the user requests information about the parameter. If a 
description exists, you may wish to modify it so that it does not repeat 
information provided by the messages. This suggestion also applies to the other 
descriptions in the HELP members. Keep in mind, though, that the user can 
request help when not responding to prompt mode messages. 

Note: If you insert a )P for only some of the positional parameters for a given 
command or for a given subcommand, unpredictable results may occur when 
parse processing issues a HELP command for one of its positional parameters. 

For example, if you want to enable parse processing to generate a HELP 
command for the entry name positional parameter of the DELETE command, 
update the text of the DELETE HELP member as follows: 

)0 OPERANDS 

) P ' ENTRYNAME ' 

. (description of entryname) 



By updating the DELETE member accordingly, you also enable the user to 
request information about the entryname positional parameter when the user is 
not being prompted for it. (See TSO/E Command Language Reference for the 
syntax of the HELP command.) 
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Chapter 4. MVS/Extended Architecture Considerations 



This section discusses considerations for MVS/Extended Architecture, with TSO 
Extensions (TSO/E 5665-285) installed, in terms of its impact on the tasks 
documented in this manual. You should be familiar with the publications that 
describe comprehensive programming considerations for MVS/Extended 
Architecture, as well as with those that describe the routines and macros discussed 
in this manual. Henceforth, MVS/Extended Architecture is referred to as 
MVS/XA. 

Note: Interfaces for service routines and macro instructions mentioned in this 
section are covered in more detail in the sections of this manual describing the 
individual service routines and macro instructions. 



31-Bit Addressing - General Interface Considerations 



The interfaces described in this section reflect what is possible on an MVS/XA 
system. When determining the attributes and linkage conventions for a program, 
you should analyze the program's individual interfaces and its overall interactions 
with other programs. This section provides general guidelines for making these 
determinations. 

MVS/XA requires that addressing modes and program residency be considered 
when determining linkage conventions. See "Specific Interfaces and Functions" 
later in this section for brief descriptions of those considerations for the service 
routines and macro instructions described in this manual. 

Assuming you are running programs on an MVS/XA system, you might want to 
take advantage of the added virtual storage provided by extended addressing, or 
you might want to prepare for doing so in the future. Before describing linkage 
considerations, it is important to note that if a program is to be run on MVS/370 
systems or on both MVS/370 and MVS/XA systems, it cannot perform any 
functions unique to MVS/XA. 

Some MVS/XA macro instructions are downward incompatible; their MVS/XA 
expansions do not function correctly in MVS/370. Of the macros discussed in this 
manual, ATTACH, ESTAE, FESTAE, and ST AX are downward incompatible. 
For a description of how to generate the desired level of a macro instruction, refer 
to SPL: System Macros and Facilities. 
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When making linkage decisions, you should analyze: 

• Who passes control to whom 

• Whether return is desired 

• AMODE and RMODE attributes 

The first two items are discussed in SPL: 31-Bit Addressing. 

The following discussion provides a general description of AMODE and RMODE 
attributes; it does not attempt to cover AMODE and RMODE considerations in 
depth. For a detailed discussion of 31 -bit addressing, refer to SPL: 31 -Bit 
Addressing. 

The following paragraphs pertain to programs running exclusively in 370-XA 
mode. 



AMODE = 24, RMODE = 24 



Programs with these attributes expect to (or are designed to) receive control in 
24-bit addressing mode, and are loaded below 16 megabytes. 

If you do not assign AMODE and RMODE attributes to a program, the 
attributes default to AMODE = 24 and RMODE = 24. With the exception of the 
TEST command processor, which has the AMODE = 31 and RMODE = 24 
attributes, the IBM-supplied terminal monitor program and command processors 
have these attributes, and are loaded below 16 megabytes. 



AMODE = ANY, RMODE = 24 



AMODE = 31 



AMODE = ANY indicates that a program expects to (or is designed to) receive 
control in the addressing mode of the program that invoked it. Note that a 
program with the AMODE = ANY attribute may have to switch addressing 
modes for certain processing. However, such a program must switch back to the 
addressing mode in which it received control before returning to the caller. 

AMODE = ANY programs must be given the RMODE = 24 attribute. 

AMODE = ANY does not indicate whether the program should be passed input 
that resides below 16 megabytes; the particular interfaces should be analyzed to 
determine where input may reside. However, a program should meet certain 
criteria in order to be assigned the AMODE = ANY attribute. Refer to SPL: 
31-Bit Addressing for a description of the criteria. 



AMODE = 31 indicates that a program expects to (or is designed to) receive 
control in 31 -bit addressing mode. Such a program may have the RMODE = 24 
or RMODE = ANY attribute, depending on its residency requirements. 
Regardless of the program's RMODE attribute, the residency of its input depends 
on the program's requirements. The program may require that some of its input 
reside below 16 megabytes, while other input may reside anywhere. 
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A program that runs exclusively in 31 -bit addressing mode (AMODE = 31) may 
do so provided it complies with the restrictions of invoking, and being invoked 
by, programs that run in 24-bit addressing mode (AMODE = 24 or 
AMODE = ANY). 

Refer to SPL: 31-Bit Addressing for more information on the AMODE = 31 
attribute. 



Specific Interfaces and Functions 



The interfaces described in this section reflect what is possible on an MVS/XA 
system. When determining the attributes and linkage conventions for a program, 
you should analyze both the program's individual interfaces and its overall 
interactions with other programs. This section provides specific guidelines for 
making these determinations. 



Control Program Interfaces 



With the exception of the TEST command processor, which the TMP loads below 
16 megabytes and invokes in 31 -bit addressing mode, the IBM-supplied command 
processors are loaded below 16 megabytes and must receive control in 24-bit 
addressing mode. Refer to "Testing a Newly- Written TMP or CP - The TEST 
Command" for additional information on the TEST command and its services. 

The command processor parameter list (CPPL) passed by IBM-supplied control 
programs resides below 16 megabytes. 

User- written TMPs and CPs may execute in either 24- or 3 1 -bit addressing mode 
provided they follow the restrictions involved in invoking programs that have 
24-bit dependencies. When assigned the AMODE = 3 1 attribute, they may be 
loaded above 16 megabytes (RMODE = ANY), and passed input that resides 
above 16 megabytes. 



Service Routine Interfaces 



The data type processor (IKJEBEPS) and the STA interface routine (IKJEHSIR) 
must be invoked in 24-bit addressing mode. All input passed to these two 
routines must reside below 16 megabytes. 

If a program running in 31 -bit addressing mode invokes one of these two routines, 
the LINK macro should be used to invoke it because LINK does not require the 
invoking program to switch to 24^bit addressing mode. In this case, LINK 
switches to 24-bit mode on behalf of the invoking program. If a program is 
loaded above 16 megabytes, it must use LINK to invoke IKJEBEPS or 
IKJEHSIR. 
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Macro Interfaces 



The following service routines can be invoked in either 24- or 31 -bit addressing 
mode, but all input passed to these routines must reside below 16 megabytes. 
These routines execute in 24-bit addressing mode and return control in the same 
addressing mode in which they are invoked: 

IKJEHCIR Catalog information routine 
IKJEHDEF Default service routine 

The following service routines can be invoked in either 24- or 31 -bit addressing 
mode. When invoked in 31 -bit addressing mode, these routines may be passed 
input that resides above 16 megabytes. These routines execute and return control 
in the same addressing mode in which they are invoked: 

IKJDAIR Dynamic allocation interface routine 

IKJEFF18 DAIRFAIL 

IKJEFF19 GNRLFAIL/VSAMFAIL 

IKJEFTSR TSO service routine 

The following service routines can be invoked in either 24-bit or 31 -bit addressing 
mode. They execute in 31 -bit addressing mode and can accept input above or 
below 16 megabytes. These routines will return control in the same addressing 
mode in which they are invoked: 

IKJEFF02 TSO message issuer routine 

IKJGETL GETLINE service routine 

IKJPARS Parse service routine 

IKJPTGT PUTGET service routine 

IKJPUTL PUTLINE service routine 

IKJSCAN Command scan service routine 

IKJSTCK STACK service routine 

IKJCT441 CLIST variable access routine 

Note that the list source descriptor (LSD) must reside below 16 megabytes. The 
output line descriptor (OLD) can reside above 16 megabytes. 

ST AX (specify terminal attention exit routine) may be invoked in either 24- or 
31 -bit addressing mode. Refer to "Attention Interruption Handling -- The ST AX 
Service Routine" for more information. 

Refer to "Passing Control to the TSO Service Routines" later in this book for 
more detailed descriptions of interfacing with the routines listed in this section. 



Figure 4-1 shows the MVS/Extended Architecture rules for the macros discussed 
in this manual. 

Note: In Figure 4-1, a dash (-) indicates that the category does not apply to the 
macro because the macro does not generate executable code. The addressing 
mode of the program that accesses the data generated by the macro must agree 
with the residence of the data. 
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Macro 


(X) May Be Issued In 


(P) May Be Issued by Program 
(I) Input May Be 


24-Bit Mode 


31-Bit Mode 


Below 16Mb 


Above 16Mb 


ATTACH 


X 


X 


LP 


LP 


CALL 


X 


X 


LP 


LP 


CALLTSSR 


X 


X 


P 


P 


ESTAE 


X 


X 


LP 


LP 


FESTAE 


X 


X 


LP 


LP 


GETLINE 


X 


X 


LP 


LP 


GTSIZE 


X 


X 


P 


P 


GTTERM 


X 




P 




IKJENDP 


- 


- 


P 


P 


IKJIDENT 


- 


- 


P 


P 


IKJKEYWD 


- 


- 


P 


P 


IKJNAME 


- 


- 


P 


P 


IKJOPER 


- 


- 


P 


P 


IKJPARM 


- 


- 


P 


P 


IKJPOSIT 


- 


- 


P 


P 


IKJRLSA 


X 


X 


P 


P 


IKJRSVWD 


- 


- 


P 


P 


IKJSUBF 


- 


- 


P 


P 


IKJTERM 


- 


- 


P 


P 


IKJTSMSG 


- 


- 


P 


P 


LINK 


X 


X 


LP 


LP 


LOAD 


X 


X 


LP 


LP 


PUTGET 


X 


X 


LP 


LP 


PUTLINE 


X 


X 


LP 


LP 


RTAUTOPT 


X 


X 


P 


P 


SAM Macros 


X 




LP 




SPAUTOPT 


X 


X 


P 


P 


STACK 


X 


X 


LP 


LP 


STAE 


X 




LP 




STATTN 


X 




LP 




STAUTOCP 


X 


X 


P 


P 


STAUTOLN 


X 




LP 




ST AX 


X 


X 


LP 


See section on 
STAX. 


STBREAK 


X 




LP 




STCC 


X 




LP 




STCLEAR 


X 
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Figure 4-1 (Part 1 of 2). MVS/XA Interface Rules for Macro Instructions 
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Figure 4-1 (Part 2 of 2). MVS/XA Interface Rules for Macro Instructions 



Notes on Figure 4-1 



ATTACH, LINK, LOAD, XCTL 

A program may issue the ATTACH, LINK, LOAD, and XCTL macro 
instructions while executing in either 24- or 31 -bit addressing mode. These 
system services determine where to load the requested program in storage 
and in which addressing mode to invoke it based on the program's AMODE 
and RMODE attributes. Note that LOAD only loads a program; it does 
not invoke it. LOAD returns the address of the loaded program. The 
high-order bit of this address reflects the AMODE attribute of the loaded 
program. 

If a program is invoked via a LINK, ATTACH, or XCTL macro, it receives 
control in the addressing mode specified or allowed by its AMODE 
attribute. On the other hand, if a program branches to another program 
without changing addressing modes via the BASSM or BSM branch 
instructions, the requested program receives control in whatever addressing 
mode is active at the time of the branch ~ that is, in the addressing mode of 
the caller. 

For more information on these macros, refer to System Macros and 
Facilities. 

CALL 

You may use the CALL macro to invoke a program if that program may be 
invoked in the current addressing mode. 

CALLTSSR 

The CALLTSSR macro instruction may be issued in either 24- or 31 -bit 
addressing mode. See "Passing Control to the TSO Service Routines" later 
in this book for more information on issuing the CALLTSSR macro. 
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ESTAE, FESTAE, STAE, ESTAI 

The ESTAE and FESTAE macros may be issued in either 24- or 31 -bit 
addressing mode. Refer to "ESTAE/ESTAI Exit Routines ~ Intercepting 
an ABEND" for more information. Use of the STAE macro and the 
ESTAI operand on the ATTACH macro to establish recovery exits and 
routines is not recommended. If they are used, the recovery exits and 
routines must receive control in 24-bit addressing mode ~ that is, the STAE 
and ATTACH macros must be issued in 24-bit addressing mode. 

ESTAI 

See ESTAE. 

FESTAE 

See ESTAE. 

GETLINE, PUTGET, PUTLINE, STACK 

The GETLINE, PUTGET, PUTLINE, and STACK macros can be issued 
in either 24-bit or 31 -bit addressing mode. These routines execute in 31 -bit 
addressing mode and return control in the same addressing mode in which 
they are invoked. Input passed to these routines may reside above or below 
16 megabytes. However, if you use the STACK macro, the list source 
descriptor (LSD) must reside below 16 megabytes. 

IKJTSMSG 

The IKJTSMSG macro may be issued by a program loaded below or above 
16 megabytes. Refer to "Message Handling" for a description of the 
standard and extended formats of the input parameter list for IKJEFF02. 

LINK 

See ATTACH. 

LOAD 

See ATTACH. 

Parse Macros 

If the parse service routine is invoked in 31 -bit addressing mode, the parse 
parameter list, mapped by IKJPPL, may reside above 16 megabytes and the 
parse macro instructions may be issued by a program loaded above 1 6 
megabytes. See Figure 4-1 for a list of the parse macros and their linkage 
requirements. The IKJRLSA parse macro may be issued in either 24- or 
31 -bit addressing mode. 

PUTGET 

See GETLINE. 

PUTLINE 

See GETLINE. 

SAM Macros 

The sequential access method (SAM) terminal macro instructions must be 
issued in 24-bit addressing mode. 



Chapter 4. MVS/Extended Architecture Considerations 4-7 



STACK 

See GETLINE. 

STAE 

See ESTAE. 

STAX 

A program may issue the STAX macro in either 24- or 31 -bit addressing 
mode. Refer to "Specifying a Terminal Attention Exit -- The STAX Macro 
Instruction" for specific restrictions. 

SVC 93 (TGET, TPUT, TPG) 

SVC93 (TGET, TPUT, and TPG macros) executes in 24-bit addressing 
mode. All input passed to SVC93 must reside below 16 megabytes. 
Programs can invoke TGET, TPUT, and TPG in 24-bit or 31 -bit addressing 
mode. 

SVC 94 (Terminal Control Macros) 

SVC 94 (terminal control macros) executes in 24-bit addressing mode. With 
a few exceptions, terminal control macros must be issued in 24-bit 
addressing mode. The exceptions are the GTSIZE, RTAUTOPT, 
SPAUTOPT, and STAUTOCP terminal control macros, which may be 
issued in 31 -bit addressing mode. See Figure 4-1 for a list of the terminal 
control macros and their linkage requirements. 

TGET, TPUT, TPG 

See SVC 93. 

Terminal Control Macros 

See SVC 94. 

XCTL 

See ATTACH. 



31-Bit Indirection Symbol 



When the EXTENDED keyword is specified on the IKJPOSIT parse macro 
instruction, parse accepts addresses above 16 megabytes and allows the use of the 
31 -bit indirection symbol, ?, in indirect addresses and in address expressions. 
Refer to "Using the Parse Service Routine (IKJPARS)" for more information. 
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Chapter 5. Invoking Other Programs or Commands With the TSO 
Service Routine 



The TSO service routine allows a TSO user to invoke a command or program 
from an unauthorized environment. The invoked program or command processor 
can then be processed as it would if invoked from an authorized environment. 
Any unauthorized program or command processor that uses the TSO service 
routine can ignore the consideration of authorized or unauthorized environments 
and programs. However, an authorized program or command processor can use 
the TSO service routine to invoke only authorized programs or command 
processors. The TSO service facility can be invoked in both foreground and 
background TSO sessions by either command or a program. 
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Figure 5-1. TSO Service Routine 



Note: The seven parameters in this figure do not have to be contiguous to each 
other in storage. 
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Program Interface to TSO Commands or Programs 



The program interface to TSO commands or programs allows programs running 
under TSO to invoke any TSO command processor or other program whether 
the command or program runs authorized or unauthorized. It allows you to 
invoke the full range of TSO services from your programs without compromising 
MVS system integrity. 

For example, an applications program written in PLI, COBOL, assembler, or any 
of the other IBM supported programming languages can use the interface, 
IKJEFTSR (alias name, TSOLNK), to invoke the ALLOCATE command 
processor to bring about dynamic allocation of data sets. 



Invoking the TSO Service Routine 



IKJEFTSR is invoked according to the rules of the applications programming 
language in use. The following example (Figure 5-2) is an assembler applications 
program invoking a TSO command. If a program is invoked instead of a 
command, a seventh parameter may be used to pass parameters to the invoked 
program. 
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Figure 5-2 (Part 1 of 2). Invoking an Authorized Command Using IKJEFTSR 
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Figure 5-2 (Part 2 of 2). Invoking an Authorized Command Using IKJEFTSR 

Notes: 



1. The syntax of the seven parameters must follow the conventions of the 
applications language being used. 

2. The seventh parameter is optional and can only be used when invoking a 
program. 



TSO Service Routine Parameters 



The seven parameters serve the following function: 
1 . This parameter identifies a full word of flags. 

a. Bytes one and two are zeros. 

b. Byte three is the error processing flag byte. It contains one of the 
following: 

• X'OO' to show that no dump should be taken in case of an ABEND. 

• X'01' to show that a dump should be taken in case of an ABEND. 
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c. Byte four is the function flag byte. It contains one of the following: 

• X'01' one to show that a TSO command is being invoked. 

• X'02' to show a program is being invoked. 

2. The second parameter identifies the function buffer, which contains the name 
of the command or program being invoked. 

3. The third parameter contains the length of the function buffer (parameter 2). 

4. The fourth parameter identifies the function return code. The function 
return code is the return code found in register 15 when the requested 
program or command completes. 

Note: See Figure 5-3 for an explanation of the IKJEFTSR return codes. 

5. The fifth parameter identifies the function abend reason code or the TSO 
Service Routine reason code. If the TSO Service Routine has a return code of 
12 in register 15, this field contains a reason code that is associated with the 
abend code pointed to by parameter 6. If the TSO Service Routine return 
code is 20, this field indicates an error in the IKJEFTSR parameter list. 

Note: See Figure 5-4 for an explanation of the IKJEFTSR reason codes. 

6. The sixth parameter identifies a field to contain the ABEND code, if the 
requested program or command ends unsuccessfully. 

7. The seventh parameter identifies the function parameter list. This parameter 
is optional, and can only be coded when a program (not a TSO command) is 
being invoked. This parameter list is a variable length list and the high order 
bit of the last address must be on to indicate the end of the list. 

The function parameter list: 

a. Must have 1 to 4 parameters 

b. The high order bit of the last parameter must be on 

c. Parameters 1-3 

1) A half word contains the parameter length in binary bytes, 
immediately followed by 

2) A variable length data string 

d. The last parameter 

1) A full word containing 2 bytes of binary zeros, immediately followed 
by 

2) Two bytes containing the binary number of full words of data, 
immediately followed by 

3) A variable length data string 

The exact format of this parameter list will vary depending on the program 
being invoked. 
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Return Codes 


Meaning 





IKJEFTSR and the requested program or command completed successfully. 


4 


The invoked function (program or command) had a non-zero return code in 
register 15. The function return code field pointed to by the 4th parameter 
contains the contents of register 1 5 upon completion of the invoked program or 
command. 


8 


The invoked function was terminated because of an attention. If the applications 
programmer wishes to notify the end user his application program should issue a 
message. 


12 


The invoked function abended. The abend code field pointed to by the 6th 
parameter contains the abend code. The reason code field pointed to by the 5th 
parameter contains the reason code associated with the abend. 


16 


One of the first 6 parameters in the parameter list contains addresses of data in 
protected storage. 


20 


The IKJEFTSR parameter list contains an error. The reason code field pointed 
to by the 5th parameter contains the reason code associated with the error. 


24 


The TSO routines associated with IKJEFTSR encountered an unexpected failure. 


28 


The invoker of IKJEFTSR has AMODE 24, and the parameter list contains 
31 -bit addresses. (MVS/XA only) 



Figure 5-3. IKJEFTSR Return Codes 
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Reason Codes 


Meaning 


4 


The length of the parameter list was invalid. 
One of the following is true: 

• The high order bit of the last parameter must be on to indicate 
the end of the list. 

• The high order bit is on in any of the first five parameters. 

• More than seven parameters are coded. 


8 


The reserved flags (bytes 1 and 2) of the function(program or command) flag 
field pointed to by the first parameter are non-zero. 


12 


The function(program or command) flag byte (byte 4) of the flag field pointed to 
by the first parameter was invalid. It should contain a decimal one for a 
command or a decimal two for a program. 


16 


The function (program or command) flag byte (byte 4) of the flag field pointed to 
by the first parameter specified a command (contained a decimal one). However, 
a seventh parameter (program parameter list) was also coded. The seventh 
parameter can only be coded for the program function. 


20 


The abend processing flag byte is invalid. This byte (byte 3) of the flag field 
pointed to by the first parameter should contain either a decimal zero to request 
a dump, or a decimal one to indicate no dump is to be taken. 


24 


IKJEFTSR was invoked from a non-TSO environment. This service can only be 
used in a TSO (foreground or background) environment. 


28 


The function buffer length is invalid. The function buffer pointed to by the 2nd 
parameter must be greater than zero and less than 32K-5. 


32 


The program parameter list( pointed to by the seventh parameter of the TSO 
service routine parameter list) either resides in protected storage or contained 
addresses of data in protected storage. 


36 


The program parameter list pointed to by the 7th parameter is invalid. The 
function parameter list: 

a. Must have 1 to 4 parameters 

b. The high order bit of the last parameter must be on 

c. Parameters 1-3 

(1) A half word contains the parameter length in binary bytes, 
immediately followed by 

2) A variable length data string 

d. The last parameter 

(1) A full word containing 2 bytes of binary zeros, immediately 
followed by 

(2) 2 bytes containing the binary number of full words of data, 
immediately followed by 

(3) A variable length data string 


40 


The requested function (program or command) was not found. 


44 


IKJSCAN detected a syntax error in the function (program or command) name. 


48 


A command began with "%". CLISTs are not supported. 


52 


Unsupported background function(program or command). 


56 


The function(program or command) is authorized, but the a copy of the function 
could not be found in an authorized library. 



Figure 5-4. IKJEFTSR Reason Codes 

For further information about the TSO service routine see Terminal Monitor 
Program and Service Routines Logic. 
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Chapter 6. Program Access to CLIST Variables 



This service allows any application program to examine and manipulate CLIST 
variables. Programs can access CLIST variables by calling or linking to the 
CLIST variable access module (IKJCT441). 

IKJCT441 provides the following functions: 

• Update or create a CLIST variable value. If the variable does not exist, 
IKJCT441 creates it. 

• Update a CLIST variable. If the variable does not exist, IKJCT441 does not 
create it. 

• Return a CLIST variable value. If a caller requests to return the value for a 
variable that does not exist, IKJCT441 creates it. 

• Return all active CLIST variables and their values. 

Some CLIST variables are called control variables. Control variables are 
variables that have a special meaning in a CLIST. Generally, they provide 
information about the environment during CLIST execution. You can change or 
assign values to only some of these control variables. See TSO Extensions 
CLISTs: Implementation and Reference for a list of the control variables that you 
can modify and a list of the control variables that you cannot modify. 

Figure 6-1 shows how to obtain the address of IKJCT441 from the TSO vector 
table (TSVT). The figure also shows the caller's parameter list. 
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Figure 6-1. Program Access to CLIST Variables 

The parameter list allows callers to send input to and receive output from 
IKJCT441. The symbolic names and descriptions of the caller's parameters 
follow: 

Parameter Function 

ECODE Entry code. The entry code is a number that indicates to IKJCT441 the function that is 

being requested. It is a constant located in the TSVT. 

NAMEPTR Address of the variable name. 

NAMELEN Length of the variable name. 

VALUEPTR Address of the variable value. 

VALUELEN Length of the variable value. 

TOKEN Used only when finding all active CLIST variables. It contains zero or the address of an 

internal CLIST control variable that points to the last variable the caller received. The 
caller must turn on the high-order bit of this parameter to indicate that it is the last 
parameter in the list. 

In MVS/XA, callers executing in 31 -bit addressing mode can pass data residing 
above the 16 megabyte line as input to IKJCT441. 
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Update or Create a CLIST Variable Value 

Before invoking IKJCT441 to update or create a variable, the caller: 

• Must specify each of the parameters in the parameter list. 

• Set the value of TOKEN to zero. 

• Turn on the high-order bit of the sixth word of the parameter list. 

Figure 6-2 shows an example of how to invoke IKJCT441 to update a variable 
value or create that variable if it does not exist. 
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Figure 6-2 (Part 1 of 2). Update or Create a CLIST Variable Value 
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Figure 6-2 (Part 2 of 2). Update or Create a CLIST Variable Value 



IKJCT441 places one of the following return codes in register 15, but does not 
change any of the parameters in the caller's parameter list. 



Content 

12 
16 

32 
36 

40 
44 



Meaning 

IKJCT441 updated or created the variable. 

The variable is a label, and IKJCT441 did not update it. 

The variable is a CLIST built in function or a control variable that the user cannot 
modify, such as &SYSDATE, and IKJCT441 did not update it. 

A storage management (GETMAIN/FREEMAIN) failure occurred. 

The length of the variable name is less than 1 or greater than 252, or the length of the 
value of a symbolic variable is less than 1 or greater than 32,678. 

The caller's parameter list contains an error, or the caller is not in a CLIST environment. 

The entry code is not valid. 



Update a CLIST Variable Value Only 

Before invoking IKJCT441 to update a variable, the caller: 

• Must specify each of the parameters in the parameter list. 

• Set the value of TOKEN to zero. 

• Turn on the high-order bit of the sixth word of the parameter list. 

Figure 6-3 shows an example of how to invoke IKJCT441 to update a variable 
value. If the variable does not exist, IKJCT441 does not create it, but returns to 
the caller with a return code of X'52\ 
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* 
* 


INVOKE THE VARIABLE ACCESS SERVICE 






LTR 


R15,R15 


VERIFY TSVT ADDRESS PRESENT 






BNZ 


CALL441 


IF PRESENT, CALL IKJCT441 




LINK441 


LINK 


EP=IKJCT441, 




* 






PARAM=(ECODE, 


ENTRY CODE 


* 






NAMEPTR, 


POINTER TO VARIABLE NAME 


* 






NAMELEN , 


LENGTH OF VARIABLE NAME 


* 






VALUEPTR , 


POINTER TO VARIABLE VALUE 


* 






VALUELEN , 


LENGTH OF VARIABLE VALUE 


* 






TOKEN) , 


TOKEN TO VARIABLE ACCESS SERVICE 


* 






VL=1 


CAUSES HI BIT ON IN THE PARM LIST 






B 


RET441 






CALL441 


CALL 


(15), 




* 






(ECODE, 


ENTRY CODE 


* 






NAMEPTR , 


POINTER TO VARIABLE NAME 


* 






NAMELEN , 


LENGTH OF VARIABLE NAME 


* 






VALUEPTR , 


POINTER TO VARIABLE VALUE 


* 






VALUELEN , 


LENGTH OF VARIABLE VALUE 


* 






TOKEN ) , 


TOKEN TO VARIABLE ACCESS SERVICE 


* 


* 




VL 


CAUSES HI BIT ON IN THE PARM LIST 




RET441 


LTR 


R15,R15 


CHECK RETURN CODE 




* 


BNZ 


ERRORRTN 






* 
ERRORRTN 


DS 


OH 








LA 


R08,TSVRUNDF 


OBTAIN NO IMPLICIT RETURN CODE 






CLR 


R15,R08 


DETERMINE IF UNDEFINED VARIABLE 




* 


BNZ 


EXITCODE 


IF NOT, THEN EXIT 




* 
* 
* 


ISSUE 


ERROR MESSAGES 


OR TAKE ANY APPROPRIATE ACTION 





Figure 6-3 (Part 1 of 2). Update a CLIST Variable Value Only 



6-6 TSO/E Guide to Writing a TMP or a CP 



EXITCODE 


L 


R13,4( ,R13) 


CALLER'S SAVEAREA 




L 


R14,12( ,R13) 


RESTORE REGISTER 14 




LM 


R00,R12,20(R13) 


RESTORE REMAINING REGISTERS 




BR 


R14 


RETURN TO CALLER, REGISTER 15 CONTAINS 


* 
* 






THE 


RETURN CODE FROM IKJCT441 


* 
NAME 


DC 


CL12 ' VARIABLENAME ' 


NAME OF THE VARIABLE 


NAMELEN 


DC 


F*12' 




LENGTH OF THE VARIABLE NAME 


VALUE 


DC 


CL3'YES' 




VARIABLE VALUE 


VALUELEN 


DC 


F'3' 




LENGTH OF THE VARIABLE VALUE 


NAMEPTR 


DC 


A (NAME) 




POINTER TO THE VARIABLE NAME 


VALUEPTR 


DC 


A (VALUE) 




POINTER TO THE VARIABLE VALUE 


TOKEN 


DC 


F'O' 




TOKEN (UNUSED HERE) 


ECODE 


DC 


A(TSVNOIMP) 




ENTRY CODE FOR NO IMPLICIT SETTING 


* 








OF VALUES. IF THE SYMBOLIC VARIABLE 


* 








NAME HAD NOT BEEN PREVIOUSLY DEFINED 


* 








IKJCT441 WILL ISSUE THE RETURN CODE 


* 








of 52 (TSVRUNDF) . 


SAVEAREA 


DS 
END 


18F 







Figure 6-3 (Part 2 of 2). Update a CLIST Variable Value Only 



IKJCT441 places one of the following return codes in register 15, but does not 
change any of the parameters in the caller's parameter list. 



Content 

12 
16 

32 
36 

40 
44 

52 



Meaning 

IKJCT441 updated the variable. 

The variable is a label, and IKJCT441 did not update it. 

The variable is a CLIST built-in function or a control variable that the user cannot 
modify, such as &SYSDATE, and IKJCT441 did not update it. 

A storage management (GETMAIN/FREEMAIN) failure occurred. 

The length of the variable name is less than 1 or greater than 252, or the length of the 
value of a symbolic variable is less than 1 or greater than 32,678. 

The caller's parameter list contains an error, or the caller is not in a CLIST environment. 

The entry code is not valid. 

The variable does not exist, and IKJCT441 did not create it. 
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Return the Value of a CLIST Variable 

Before invoking IKJCT441 to return the value of a CLIST variable, the caller: 

• Must specify: 

- Entry code (ECODE) 

- Address of the variable name (NAMEPTR) 

- Length of the variable name (NAMELEN). 

• Set the value of TOKEN to zero. 

• Turn on the high-order bit of the sixth word of the parameter list. 

Figure 6-4 shows an example of how to invoke IKJCT441 to return the value of a 
CLIST variable. 
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LOOK 


CSECT 








CVTPTR 


EQU 


16 






CVTTVT 


EQU 


X'9C 






R15 


EQU 


15 






R14 


EQU 


14 






R13 


EQU 


13 






R12 


EQU 


12 






Rll 


EQU 


11 






R9 


EQU 


9 






R8 


EQU 


8 






R7 


EQU 


7 






RO 


EQU 











IKJTSVT 






LOOK 


CSECT 










STM 


R14,R12,12(R13) 


SAVE CALLER'S REGISTERS 






BALR 


R12,0 


ESTABLISH ADDRESSABILITY 






USING 


*,R12 


BASE REGISTER OF EXECUTING PROGRAM 






ST 


R13,SAVEAREA+4 


CALLER'S SAVE ARE A ADDRESS 






LA 


R 15, SAVE AREA 


EXECUTING PROGRAM'S SAVEAREA ADDRESS 






ST 


R15,8( ,R13) 


EXECUTING PROGRAM'S SAVEAREA ADDRESS 




* 


LA 


R 13, SAVE ARE A 


EXECUTING PROGRAM'S SAVEAREA ADDRESS 




* 


L 


R15, CVTPTR 


ESTABLISH 






L 


R15, CVTTVT ( ,R15) ADDRESSABILITY TO THE 




* 


L 


R15,TSVTVACC-TSVT( ,R15) VARIABLE ACCESS ROUTINE 




* 

* 


INVOKE THE VARIABLE ACCESS SERVICE 






LTR 


R15,R15 


VERIFY TSVT ADDRESS PRESENT 






BNZ 


CALL441 


IF PRESENT, CALL IKJCT441 




LINK441 


LINK 


EP=IKJCT441 / 




* 






PARAM=(ECODE, 


ENTRY CODE 


* 






NAMEPTR , 


POINTER TO VARIABLE NAME 


* 






NAMELEN , 


LENGTH OF VARIABLE NAME 


* 






VALUEPTR, 


POINTER TO VARIABLE VALUE 


* 






VALUELEN , 


LENGTH OF VARIABLE VALUE 


* 






TOKEN) , 


TOKEN TO VARIABLE ACCESS SERVICE 


* 






VL=1 


CAUSES HI BIT ON IN THE PARM LIST 






B 


RET441 






CALL441 


CALL 


(15), 




* 






(ECODE, 


ENTRY CODE 


* 






NAMEPTR, 


POINTER TO VARIABLE NAME 


* 






NAMELEN , 


LENGTH OF VARIABLE NAME 


* 






VALUEPTR, 


POINTER TO VARIABLE VALUE 


* 






VALUELEN , 


LENGTH OF VARIABLE VALUE 


* 






TOKEN) , 


TOKEN TO VARIABLE ACCESS SERVICE 


* 


* 




VL 


CAUSES HI BIT ON IN THE PARM LIST 




RET441 


LTR 

BNZ 

L 

L 

LA 

CR 

BNE 


R15,R15 

ERRORRTN 

R7, VALUELEN 

R8, VALUEPTR 

R9,L' VALUE 

R7,R9 

BAD 








CLC 


( L ' VALUE , R8 ) , VALUE 




* 
* 


BNE 


BAD 







Figure 6-4 (Part 1 of 2). Return a CLIST Variable Value 
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BAD 


DS 


OH 




ERRORRTN 


DS 


OH 






L 


R13,4( ,R13) 






L 


R14,12(,R13) 


RESTORE REGISTER 14 




LM 


R0,R12,20(R13) 


RESTORE REMAINING REGISTERS 




BR 


R14 


RETURN TO CALLER, REGISTER 15 CONTAINS 


* 
* 






THE RETURN CODE FROM IKJCT441 


* 

NAME 


DC 


CL12'VARIABLENAME' NAME OF THE VARIABLE 


NAMELEN 


DC 


F'12' 


LENGTH OF THE VARIABLE NAME 


VALUELEN 


DS 


F 


LENGTH OF VARIABLE VALUE 


NAMEPTR 


DC 


A ( NAME ) 


POINTER TO THE VARIABLE NAME 


VALUEPTR 


DS 


A 


POINTER TO THE VARIABLE VALUE 


VALUE 


DC 


CL3'YES' 


VARIABLE VALUE 


TOKEN 


DC 


F'O' 


TOKEN (UNUSED HERE) 


ECODE 


DC 


A(TSVERETR) 


ENTRY CODE FOR RETRIEVE 


SAVEAREA 


DS 
END 


18F 





Figure 6-4 (Part 2 of 2). Return a CLIST Variable Value 



IKJCT441 returns values for the following parameters unless specified otherwise 
by the return code: 

• VALUEPTR contains the address of the value of the variable. 

# VALUELEN contains the length of the variable value. 

IKJCT441 places one of the following return codes in register 15: 
Content Meaning 

IKJCT441 successfully returned the variable. 




4 

8 
12 

36 
40 

44 



The caller should not rescan the variable. It is an I/O variable containing an & and is not 
a variable name. 

The variable is a CLIST built-in function, such as &STR, that requires evaluation. 

The variable is a label. IKJCT441 updated VALUEPTR and VALUELEN, but the value 
of the variable is meaningless. 

The length of the variable is less than 1 or greater than 252. 

The caller's parameter list contains an error, or the caller is not in a CLIST environment. 
IKJCT441 did not update VALUEPTR and VALUELEN. 

The entry code is not valid. IKJCT441 did not update VALUEPTR and VALUELEN. 



6-10 TSO/E Guide to Writing a TMP or a CP 



Return all Active CLIST Variables and their Values 



To list all the CLIST variables and their values, the caller invokes IKJCT441 once 
for each existing CLIST variable. The caller sets TOKEN to zero before invoking 
IKJCT441 for the first time. When the value in TOKEN is zero, IKJCT441 
assumes this is the beginning of a list. Before returning to the caller, IKJCT441 
places the address of an internal CLIST control variable in TOKEN and uses this 
value on subsequent invocations to find the next variable. The caller must not 
change the value that IKJCT441 places in TOKEN. When there are no more 
variables, IKJCT441 places a zero in TOKEN and sets the appropriate return 
code. 

Before invoking IKJCT441 to find all the CLIST variables, the caller must: 

• Specify the entry code. 

• Set TOKEN to zero on the first entry. 

• Turn on the high-order bit of the sixth word of the parameter list. 

Figure 6-5 on page 6-12 shows an example of how to invoke IKJCT441 to find 
all CLIST variables and their values. 
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LOCATE 


CSECT 




CVTPTR 


EQU 


16 


CVTTVT 


EQU 


X'9C 


R15 


EQU 


15 


R14 


EQU 


14 


R13 


EQU 


13 


R12 


EQU 


12 


Rll 


EQU 


11 


R9 


EQU 


9 


R8 


EQU 


8 


RO 


EQU 






LOCATE 



LOOP 



IKJTSVT 

CSECT 

STM R14,R12,12(R13; 

BALR R12,0 

USING *,R12 

ST Rl3,SAVEAREA+4 

LA R 15, SAVE ARE A 

ST R15,8(,R13) 

LA R 13, SAVE ARE A 



SAVE CALLER'S REGISTERS 

ESTABLISH ADDRESSABILITY 

BASE REGISTER OF EXECUTING PROGRAM 

CALLER'S SAVEAREA ADDRESS 

EXECUTING PROGRAM'S SAVEAREA ADDRESS 

EXECUTING PROGRAM'S SAVEAREA ADDRESS 

EXECUTING PROGRAM'S SAVEAREA ADDRESS 



DS OH 

L R15, CVTPTR ESTABLISH 

L R15, CVTTVT ( ,R15) ADDRESSABILITY TO THE 

L R15,TSVTVACC-TSVT( ,R15) VARIABLE ACCESS SERVICE 

INVOKE THE VARIABLE ACCESS SERVICE 



VERIFY TSVT ADDRESS PRESENT 
IF PRESENT, CALL IKJCT441 

ENTRY CODE 

POINTER TO VARIABLE NAME 

LENGTH OF VARIABLE NAME 

POINTER TO VARIABLE VALUE 

LENGTH OF VARIABLE VALUE 

TOKEN TO VARIABLE ACCESS SERVICE 

CAUSES HI BIT ON IN THE PARM LIST 



ENTRY CODE 

POINTER TO VARIABLE NAME 

LENGTH OF VARIABLE NAME 

POINTER TO VARIABLE VALUE 

LENGTH OF VARIABLE VALUE 

TOKEN TO VARIABLE ACCESS SERVICE 

CAUSES HI BIT ON IN THE PARM LIST 





LTR 


R15,R15 




BNZ 


CALL441 


LINK441 


LINK 


EP=IKJCT441, 
PARAM=( ECODE, 
NAMEPTR , 
NAMELEN, 
VALUEPTR, 
VALUELEN , 
TOKEN) , 
VL=1 




B 


RET441 


CALL441 


CALL 


(15), 
(ECODE, 
NAMEPTR , 
NAMELEN, 
VALUEPTR , 
VALUELEN , 
TOKEN ) , 
VL 


* 






RET441 


C 


R15,NOMORE 




BE 


ENDUP 




LTR 


R15,R15 


* 


BNZ 


ERRORRTN 


MAINLINE 


DS 


OH 




L 


R8, NAMEPTR 




L 


R9, VALUEPTR 



Figure 6-5 (Part 1 of 2). Return all Active CLIST Variables and their Values 
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* 


ISSUE 'PUTLINE' TO WRITE VARIABLE NAME AND VALUE 


* 




— 


OR - 


* 
* 
* 


SAVE 


THE NAME AND 


VALUE IN A TABLE 


* 

* 
* 


B 


LOOP 




* 
* 

ERRORRTN 
* 


DS 


OH 




* 
* 


ANALYZE RETURN CODE 


* 


B MAINLINE 




ENDUP 


DS 


OH 






L 


R13,4( ,R13) 






L 


R14,12( ,R13) 


RESTORE REGISTER 14 




LM 


R0,R12,20(R13) RESTORE REMAINING REGISTERS 




BR 


R14 


RETURN TO CALLER, REGISTER 15 CONTAINS 


* 
* 






THE RETURN CODE FROM IKJCT441 


* 

NAMELEN 


DS 


F 


LENGTH OF NAME WILL BE RETURNED HERE 


VALUELEN 


DS 


F 


LENGTH OF VALUE WILL BE RETURNED HERE 


NAMEPTR 


DS 


A 


ADDRESS OF NAME WILL BE RETURNED HERE 


VALUEPTR 


DS 


A 


ADDRESS OF VALUE WILL BE RETURNED HERE 


TOKEN 


DC 


F'O' 


TOKEN MUST BE ZERO ON THE FIRST CALL 


* 






AND NEVER CHANGED BY THE CALLER 


ECODE 


DC 


A(TSVELOC) 


ENTRY CODE FOR THE 'LOCATE 1 SERVICE 


NOMORE 


DC 


A(TSVRNOM) 


RETURN CODE FOR NO MORE NAMES 


SAVEAREA 


DS 
END 


18F 





Figure 6-5 (Part 2 of 2). Return all Active CLIST Variables and their Values 



IKJCT441 returns values for the following parameters unless specified otherwise 
by the return code: 

• NAMEPTR contains the address of the variable name. 

• NAMELEN contains the variable name length. 

• VALUEPTR contains the address of the value of the variable. 

• VALUELEN contains the variable value length. 

• TOKEN contains zero or the address of an internal CLIST control variable 
that identifies the next variable. 
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IKJCT441 places one of the following return codes in register 15: 
Content Meaning 

IKJCT441 successfully updated the parameters for this variable. 

4 The caller should not rescan the variable. It is an I/O variable containing an & and is not 

a variable name. 

8 The variable requires evaluation. IKJCT441 did not update VALUEPTR and 

VALUELEN. The value of the variable is not relevant. 

12 The variable is a label. The value of the variable is meaningless. 

20 There are no more variables. 

40 The caller's parameter list contains an error, or the caller is not in a CLIST environment. 

IKJCT441 did not return values for any of the parameters. 

44 The entry code is not valid. IKJCT441 did not return values for any of the parameters. 
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Chapter 7. Processing Terminal Requests - The TSO Service 
Routines 



The TSO service routines process terminal requests initiated by the terminal 
monitor program (TMP), command processors (CPs), and other service routines. 
If you write your own command processors, or replace the IBM-supplied terminal 
monitor program with one of your own design, you should use the service 
routines to process terminal requests. 

The TSO service routines build, modify, or make use of various control blocks. 
The following control block DSECTS are provided in SYS1.MACLIB for your 
use, and are listed in Data Areas. 

IKJCPPL The command processor parameter list 

IKJCSOA The command scan output area 

IKJCSPL The command scan parameter list 

IKJDAPL The dynamic allocation parameter list 

IKJDAPOC DAIR entry code parameter block 

IKJDAPOO DAIR entry code parameter block 

IKJDAP04 DAIR entry code parameter block 

IKJDAP08 DAIR entry code parameter block 

IKJDAP1C DAIR entry code parameter block 

IKJDAP10 DAIR entry code parameter block 

IKJDAP14 DAIR entry code parameter block 

IKJDAP18 DAIR entry code parameter block 

IKJDAP2C DAIR entry code parameter block 

IKJDAP24 DAIR entry code parameter block 

IKJDAP28 DAIR entry code parameter block 

IKJDAP30 DAIR entry code parameter block 

IKJDAP34 DAIR entry code parameter block 

IKJDFPB The default parameter block 

IKJDFPL The default parameter list 

IKJECT The environment control table for GETLINE/PUTLINE/PUTGET/STACK 

IKJEFFDF PARMLIST to IKJEFF18 (DAIRFAIL) 

IKJEFFGF PARMLIST to IKJEFF19 (GNRLFAIL) 

IKJEFFMT PARMLIST to IKJEFF02 

IKJGTPB The GETLINE parameter block 

IKJIOPL The input output parameter list for GETLINE/PUTLINE/PUTGET/STACK 

IKJLSD The list source descriptor for STACK 

IKJPGPB The PUTGET parameter block 

IKJPPL Defines the parse parameter list 

IKJPSCB The protected step control block 

IKJPTPB The PUTLINE parameter block 

IKJSTPB The STACK parameter block 

IKJSTPL The STACK parameter list 

IKJTAIE Terminal attention interrupt element from STAX 

IKJTAXE Terminal attention exit element from STAX 

IKJTMPWA The terminal monitor program work area 

IKJTPL TEST parameter list 

IKJUPT User profile table 
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Interfacing with the TSO Service Routines 



When the terminal monitor program attaches a command processor, register 1 
contains a pointer to a command processor parameter list (CPPL) containing 
addresses required by the command processor. The CPPL is located in subpool 1 . 
The control block interface between the TMP and an attached CP is shown in 
Figure 7-1. 







ATTACH 










Terminal 
Monitor 
Program 


Command 
Processor 






Reg' 


Ster 1 






























CPPL 



























Figure 7-1. Control Block Interface between the TMP and CP 



The Command Processor Parameter List 



You must pass certain addresses contained in the CPPL to the TSO service 
routines. Your user-written command processors can access the CPPL via the 
symbolic field names contained in the IKJCPPL DSECT by using the address 
received in register 1 as a starting address for the DSECT. The use of the 
DSECT is recommended since it protects the command processor from any 
changes to the CPPL. 

The command processor parameter list, as defined by the IKJCPPL DSECT, is a 
four-word parameter list. Figure 7-2 describes the contents of the CPPL. 
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When the TMP invokes a problem program, whether a command processor or 
not, register 1 contains the address of the CPPL. The CPPL is required by any 
program that is going to use TSO service routines. If any problem program or 
user-written command processor is going to invoke an IBM-supplied command 
processor, the CPPL address must be supplied in register 1. 

With the exception of the TEST command processor, which is invoked in 31 -bit 
addressing mode and may be passed input above 16 megabytes, the IBM-supplied 
command processors and TMP require that their input reside below 16 

megabytes. 

User-written TMPs and CPs may pass input below or above 16 megabytes 
provided they adhere to the guidelines set forth in "31 -Bit Addressing ~ General 
Interface Considerations" earlier in this book. 



Number 
of Bytes 


Field 


Contents or Meaning 


4 
4 

4 
4 


CPPLCBUF 
CPPLUPT 

CPPLPSCB 
CPPLECT 


The address of the command buffer for the currently attached command 
processor. 

The address of the user profile table (UPT). The UPT is built by the 
LOGON/LOGOFF scheduler from information stored in the user 
attribute data set (UADS) and from information contained in the 
LOGON command. The address of the UPT is obtained from the 
PSCBUPT field of the protected step control block (PSCB). 

The address of the protected step control block (PSCB). The PSCB is 
built by the LOGON/LOGOFF scheduler from information stored in 
the UADS. The TMP can obtain the address of the PSCB using the 
EXTRACT macro instruction. 

The address of the environment control table (ECT). The ECT must be 
built by the TMP during its initialization process; it is used by the TSO 
service routines and by some TSO commands and subcommands. 



Figure 7-2. The Command Processor Parameter List (CPPL) 



Passing Control to the TSO Service Routines 



For a description of linkage and program residency considerations, refer to 
"Service Routine Interfaces" in the previous section. 

There are four ways you can pass control to the TSO service routines. 

1 . You can issue an I/O macro instruction without the ENTRY parameter for 
the I/O service routines. 

2. You can issue a LINK macro instruction to a service routine, but this 
requires more system overhead than other methods. 

The LINK macro instruction loads the routine in storage based on its 
RMODE attribute, and passes control to the routine in the addressing mode 
specified or allowed by its AMODE attribute. 

3. You can issue a LOAD macro instruction for a service routine and then do 
branches to the loaded routine, but this also requires more system overhead 
than other methods. 
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The LOAD macro loads the routine in storage based on its RMODE 
attribute. LOAD returns the address of the loaded program. The high-order 
bit of this address reflects the AMODE attribute of the loaded program. If 
the loaded program should not be invoked in the current addressing mode, 
the BASSM or BSM instruction may be used to set the appropriate 
addressing mode. If you use BASSM or BSM, you should ensure that the 
invoked program can return successfully. 

4. You can issue a CALLTSSR macro. CALLTSSR generates a branch to a 
TSO service routine if the routine resides in the link pack area. If the routine 
was 

not placed in the link pack area, CALLTSSR generates a LINK macro 
instruction. The CALLTSSR macro is used only for the following routines: 

IKJDAIR Dynamic allocation interface routine 

IKJEFF02 TSO message issuer routine 

IKJEHCIR Catalog information routine 

IKJEHDEF Default routine 

IKJPARS Parse routine 

IKJSCAN Command scan 

IKJEHCIR and IKJEHDEF can be invoked in either 24- or 31 -bit addressing 
mode. However, both routines execute in 24-bit addressing mode and return 
control in the caller's addressing mode. 

IKJDAIR can be invoked, and can execute, in 24- or 31 -bit addressing mode. 
When invoked in 31 -bit addressing mode, IKJDAIR may be passed input that 
resides above 16 megabytes. 

IKJEFF02, IKJPARS, and IKJSCAN can be invoked in either 24-bit or 31 -bit 
addressing mode. These routines execute in 31 -bit addressing mode and can 
accept input above or below 16 megabytes. 

Refer to the appropriate sections in this book for more information about these 
routines. 



The CALLTSSR Macro Instruction 



Figure 7-3 shows the execute form of the CALLTSSR macro instruction. There 
is no list form. Each of the operands is explained in the following figure. 
Appendix A describes the notation used to define macro instructions. 



[symbol] 


CALLTSSR 


EP=entry point name 
I~MF=/E, {list address) \~| 
j_ \ \(register) J/J 



Figure 7-3. The CALLTSSR Macro Instruction 

Note: The CVT mapping macro (CVT), found in SYS1.AMODGEN must be 
used in any module which uses the CALLTSSR macro. 
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Example 



EP = entry point name 

Specifies one of the following names: IKJDAIR, IKJEFF02, IKJEHCIR, 
IKJEHDEF, IKJPARS, IKJSCAN. 

MF = E 

Indicates that this is the execute form of the macro instruction. 

list address or (register) 

Specifies the address, or register that contains the address, of a parameter 
list to be passed to the service routine. 



This example shows how the CALLTSSR macro instruction could be used to pass 
control to the parse service routine. 



CALLTSSR EP=IKJPARS,MF=(E,PPL) 
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Chapter 8. Message Handling 



Message Levels 



TSO messages are divided into three classes: 

• Prompting messages 

• Mode messages 

• Informational messages 

Prompting messages begin with ENTER or REENTER, and require a response 
from the user. Prompting messages should be initiated by the parse service 
routine, rather than by parse validity check exits, using the text supplied by the 
command processor as the PROMPT operand of the IKJPOSIT, IKJTERM, 
IKJOPER, IKJRSVWD or IKJIDENT parse macro instructions. See "Using the 
Parse Service Routine (IKJPARS)" for a discussion of the PROMPT operand on 
these macro instructions. 

Mode messages are the READY messages sent by the terminal monitor program, 
and any other similar messages sent by command processors, such as the EDIT 
mode message sent by the EDIT command processor. They inform the user 
which command is in control and let him know that the system is waiting for him 
to enter a new command or subcommand. 

Informational messages do not require an immediate response from the user. 

Prompting and mode messages should be displayed using the PUTGET service 
routine. Informational messages should be displayed using the PUTLINE service 
routine. The TPUT routine does not support multi-level messages, message id 
stripping, and text insertion, and does not function in background mode (it acts as 
a NOP). 



Messages usually should have associated with them other messages that more fully 
explain the initial message. These messages, called second level messages, are 
displayed only if the user specifically requests them by entering a question mark 
(?)• 

Note that if the user uses PUTGET with TERMGET = ASIS, the user's terminal 
will not recognize the question mark. 

Prompting messages may have any number of second level messages. Second 
level messages, if any, are displayed when the user enters a question mark in 
response to the initial message. If the user enters a question mark after all second 
level messages have been displayed, with a few exceptions (see "Prompt Mode 
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HELP Function"), parse processing generates a HELP command to give the user 
specific information about the operand for which he is being prompted. If the 
user enters a question mark after viewing the online usage information, the NO 
INFORMATION AVAILABLE message is issued. 

An informational message can have only one second level message associated with 
it. Since many informational messages might be displayed at the terminal before 
a question mark is returned from the terminal, PUTLINE moves all second level 
informational messages to subpool 78 and chains them off the environment 
control table. This chain exists from one PUTGET for a mode message to the 
next. In other words, whenever the user can enter a new command or 
subcommand, the user can enter a question mark instead, requesting all the 
second level messages for informational messages issued during execution of the 
previous command or subcommand. If the user does not enter a question mark, 
PUTGET deletes the second level messages and frees the storage they occupy. 

Mode messages cannot have second level messages, since a question mark entered 
in response to a mode message is defined as a request for the second levels of 
previous informational messages. Your program should request all commands or 
subcommands by issuing a mode message with the PUTGET service routine so 
that second level informational messages may be properly handled. 



Effects of the Input Source on Message Processing 



Message handling is considerably affected if the input source designated by the 
input stack is an in-storage list rather than a terminal. See the explanation of the 
STACK macro instruction for a discussion of in-storage lists. In-storage lists may 
be either procedures or source lists. 

If a procedure without the prompt option is being executed, the PUTGET service 
routine does not display prompting messages, but returns an error code (12) in 
register 15. If the parse service routine issued the PUTGET macro instruction, 
the parse service routine issues an informational message to the terminal, and 
returns an error code 4 to its caller. The command processor should reset the 
input stack and terminate. If a command processor issued the PUTGET macro 
instruction, the command processor should use the PUTLINE service routine to 
write an appropriate informational message to the terminal prior to terminating. 

If a source in-storage list is being processed, prompt messages are displayed to, 
and responses read from, the terminal by the PUTGET service routine. 

If the user at the terminal has specified the "PAUSE" operand on the PROFILE 
command, PUTGET issues a special message, "PAUSE," if all of these three 
conditions exist: 

1 . A mode message is to be written out. 

2. Second level messages exist. 

3. An in-storage list is being processed. 

The user may enter either a question mark or a null line. If he enters a question 
mark, the chain of second level messages is written to the terminal. If he enters a 
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null line, control returns to the executing command processor. In either case, the 
next line from the in-storage list is returned to the command processor. 

A special situation arises if an in-storage list is being processed, second level 
messages are chained, and the user has specified NOPAUSE as an operand of the 
PROFILE command. Normally, if a subcommand encounters an error situation, 
it issues an informational message and returns. The command processor then uses 
the PUTGET service routine to issue a mode message on the assumption that the 
user can take corrective action with other subcommands. When processing from 
an in-storage list, this is not true. If NOPAUSE was specified, PUTGET returns 
an error code (12) to the calling routine. In most cases, the command processor 
should reset the input stack and terminate. If the message producing the second 
level message was purely informational and does not require corrective action, the 
command processor may set the ECTMSGF flag in the environment control table 
to delete the second level message, and reissue the PUTGET macro instruction to 
continue. 



TSO Message Issuer Routine (IKJEFF02) 



The TSO message issuer routine issues a message as a PUTLINE, PUTGET, 
write-to-operator (WTO), or write-to-programmer (WTP). You may invoke 
IKJEFF02 just to issue the message to the terminal, both to issue the message and 
return the requested message to the caller in the caller's buffers, or just to return 
the message to the caller. This process of returning the message is referred to as 
extracting the message. This routine simplifies the issuing of messages with inserts 
because hexadecimal inserts can be converted to printable characters and the same 
parameter list used to issue any message. It also makes it more convenient to 
place all messages for a command in a single CSECT or assembly module, which 
is important when message texts must be modified. Adding or updating a 
message is simpler when IKJEFF02 is used, rather than PUTLINE or PUTGET. 

Refer to "Interfacing with the TSO Service Routines" earlier in this book for a 
description of the ways in which IKJEFF02 may be invoked. Regardless of the 
linkage method used, IKJEFF02 may be invoked in either 24- or 31 -bit addressing 
mode. IKJEFF02 executes in 31 -bit addressing mode and can accept input above 
or below 16 megabytes. 

Generally, you will invoke the TSO message issuer routine via the CALLTSSR or 
LINK macro, passing the address of the input parameter list in register 1. 

The IKJEFFMT macro, which maps the input parameter list for IKJEFF02, 
allows the user to request the standard format (the default) or the extended 
format of the parameter list. The extended format must be used if the message 
inserts and/or the extract buffers being passed to IKJEFF02 reside above 16 
megabytes. If they reside below 16 megabytes, you do not need to use the 
extended format. However, all 31 -bit addresses must be valid (zero high order 
bit). Note that the MTFMT bit must reflect the format of the parameter list you 
are using. 
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Standard Format of Input Parameter List 



Offset 
Dec Hex 



12 C 
12 C 
16 10 



20 



25 
28 

32 
33 
36 
37 



14 



21 15 

24 18 



19 
1C 

20 
21 

24 
25 



Field Name 
MTPLPTR 

MTCPPLP 

MTECBP 
MTRESV1 
MTHIGH 
MTCSECTP 

MTSW1 

MTNOIDSW 

MTPUTLSW 



MTWTOSW 

MTHEXSW 

MTKEY1SW 

MTJOBISW 

MTWTPSW 

MTNHEXSW 

MTREPLYP 

MTSW2 
MT20LDSW 

MTDOMSW 

MTNOXQSW 

MTNPLMSW 

MTPGMSW 

MTEXTRCN 

MTFMT 

MTRESV2 

MTOLDPTR 

MTEXTRLN 
MTEXTRBF 
MTEXTRL2 
MTEXTRB2 



Contents 

Address of message description section of this parameter list. (The 
message description section begins with the MTCSECTP entry.) 

Address of TMP's CPPL control block (required for PUTLINE or 
PUTGET). 

Address of optional communications ECB for PUTLINE or PUTGET. 

Reserved. 

High-order bit of reserved field turned on for standard linkage. 

Address of an assembly module or a CSECT containing IKJTSMSG 
macros that build message identifications and associated texts. 

One byte field of switches. 

1 Message is printed; no messageid is needed. 

.1 Message issued as PUTLINE. (Message inserts for a second 

level message must be listed before inserts for a first level 
message.) If this bit is zero, message issued as a PUTGET, 
with second level message required and inserts for second 
level messages necessarily following inserts for first level 
messages. 

..1 Message issued as a WTO. Default is PUTGET. 

...1 .... Number translations to printable hexadecimal rather than 
default of printable decimal. 

Modeset from key 1 to key before issuing a PUTLINE or 
PUTGET message. Default is no modeset. 

Blanks are compressed from xx(yy) format inserts. Default 
is no compression. 

Message issued as WTO with write-to-programmer routing 
code. Inserts are handled the same as for PUTLINE. 
Default is PUTGET. 

1 Number translations to printable decimal, even if larger than 

X'FFFF'. Default is printable hex above X'FFFF'. 

Address of reply from PUTGET. The reply text is preceded by a 
two-byte field containing length of text plus header field. 

One byte field of switches. 

1 Field MTOLDPTR points to second level message already in 

PUTLINE/PUTGET (Output Line Descriptor) format. 
Default is IKJTSMSG format. 

.1 Delete WTP or WTO messages from the display console, 

using the delete operator message macro. 



1.. 



.1.. 



..1. 



.1. 



...1 



Override default of X" around inserts converted to printable 
hex. 



Override default of error message if PUTLINE fails. 

1... Request an error message if PUTGET fails. 

1.. Request an extract and a message. 

0. Request standard (24-bit) format of this parameter list. 

Reserved. 

Pointer to OLD for second level message, required if MT20LDSW bit 
is on. 

Length of extract buffer. 

Pointer to extract buffer supplied by caller. 

Length of extract buffer for second level message. 

Pointer to extract buffer supplied by caller for second level message. 
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Offset 




Dec 


Hex 


Field Name 


40 


28 


MTMSGID 


44 


2C 


MTINSRTS 


44 


2C 


MTLEN 


44 


2C 


MTH1GHL 


44 


2C 


MTINSRT 


45 


2D 


MTADDR 



Contents 

Message's identifier in message CSECT, padded with blanks on the 
right. 

Insert information for message. The following two fields are supplied 
for each insert. 

Length of an insert for the message. 

High-order bit is on if necessary to translate the first 1 -4 bytes of the 
insert from hexadecimal to character (printable hexadecimal or decimal 
depending on whether MTHEXSW is set to ON or OFF). 

Refers to an insert entry. 

Address of an insert for the message. 



Extended Format of Input Parameter List 



Offset 
Dec Hex Field Name 

MTPLPTR 



4 4 MTCPPLP 

8 8 MTECBP 

12 C MTRESV1 

12 C MTHIGH 

16 10 MTCSECTP 

20 14 MTSW1 

MTNOIDSW 
MTPUTLSW 







MTWTOSW 






MTHEXSW 






MTKEY1SW 






MTJOBISW 






MTWTPSW 






MTNHEXSW 


21 


15 


MTEXTRLN 


22 


16 


MTEXTRL2 


23 


17 


MTRESV3 



Contents 

Address of message description section of this parameter list. (The 
message description section begins with the MTCSECTP entry.) 

Address of TMP's CPPL control block (required for PUTLINE or 
PUTGET). 

Address of optional communications ECB for PUTLINE or PUTGET. 

Reserved. 

High-order bit of reserved field turned on for standard linkage. 

Address of an assembly module or a CSECT containing IKJTSMSG 
macros that build message identifications and associated texts. 

One byte field of switches. 

1 Message is printed; no messageid is needed. 

.1 Message issued as PUTLINE. (Message inserts for a second 

level message must be listed before inserts for a first level 
message.) If this bit is zero, message issued as a PUTGET, 
with second level message required and inserts for second 
level messages necessarily following inserts for first level 
messages. 

..1 Message issued as a WTO. Default is PUTGET. 

...1 .... Number translations to printable hexadecimal rather than 
default of printable decimal. 

1... Modeset from key 1 to key before issuing a PUTLINE or 
PUTGET message. Default is no modeset. 

Blanks are compressed from xx(yy) format inserts. Default 
is no compression. 

Message issued as WTO with write-to-programmer routing 
code. Inserts are handled the same as for PUTLINE. 
Default is PUTGET. 



.1.. 



..1. 



1 Number translations to printable decimal, even if larger than 

X'FFFF'. Default is printable hex above X'FFFF'. 

Length of extract buffer. 

Length of second extract buffer. 

Reserved. 
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Offset 
Dec Hex 



24 



25 
28 



44 



48 
48 

48 

52 



18 



19 
1C 



32 20 
36 24 
40 28 



2C 
30 

30 
30 

30 
34 



MTNPLMSW 

MTPGMSW 

MTEXTRCN 

MTFMT 

MTRESV2 

MTOLDPTR 

MTEXTRBF 
MTEXTRB2 
MTMSGID 

MTREPLYP 
MTINSRTS 

MTLEN 
MTHIGHL 

MTINSRT 
MTADDR 



1.. 



Field Name 

MTSW2 
MT20LDSW 

MTDOMSW .1.. 
MTNOXQSW ..1. 



Contents 

One byte field of switches. 



...1 



Field MTOLDPTR points to second level message already in 
PUTLINE/PUTGET (Output Line Descriptor) format. 
Default is IKJTSMSG format. 

Delete WTP or WTO messages from the display console, 
using the delete operator message macro. 

Override default of X" around inserts converted to printable 
hex. 

Override default of error message if PUTLINE fails. 

1... Request an error message if PUTGET fails. 

1.. Request an extract and a message. 

1. Request extended (31 -bit) format of this parameter list. 

Reserved. 

Pointer to OLD for second level message, required if MT20LDSW bit 
is on. 

Pointer to extract buffer supplied by caller. 

Pointer to extract buffer supplied by caller for second level message. 

Message's identifier in message CSECT, padded with blanks on the 
right. 

Address of reply from PUTGET. 

Insert information for message The following two fields are supplied 
for each insert. 

Length of an insert for the message. 

High-order bit is on if necessary to translate the first 1-4 bytes of the 
insert from hexadecimal to character (printable hexadecimal or decimal 
depending on whether MTHEXSW is set to ON or OFF). 

Refers to an insert entry. 

Address of an insert for the message. 



The return code from the TSO message issuer routine is contained in register 1 5 
as follows: 

- Message issued successfully. 

76 - Error in parameter list. A diagnostic message is also issued. 

Other - PUTLINE or. PUTGET return code. 

The IKJEFFMT macro maps the input parameter list. Specify the 
MTDSECT = YES option to obtain DSECT MTDSECTD instead of storage. 
Specify MTFORMAT = NEW on the IKJEFFMT macro to request the extended 
format. Specify MTFORMAT = OLD to request the standard format. 



8-6 TSO/E Guide to Writing a TMP or a CP 



IKJTSMSG — Describes Text and Insert Locations 



The IKJTSMSG macro is used to generate assembler language DC instructions 
describing the text and locations of inserts for a message which may be issued by 
the TSO message issuer routine (IKJEFF02). All of the messages which a 
command issues should be grouped into an assembly module consisting entirely of 
IKJTSMSG macros preceded by a CSECT card and followed by an END card. 
The last IKJTSMSG macro in the CSECT must be a dummy entry with no 
operands. 

The IKJTSMSG macro may be issued by a program loaded below or above 16 
megabytes. 

Figure 8-1 shows the syntax of the IKJTSMSG macro instruction; each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



[symbol] 



IKJTSMSG ('msgid msgtext » ) , idl [ , id2 ] 



Figure 8-1. The IKJTSMSG Macro Instruction 

msgid 

The identifier which will be displayed when the message is issued. 

msgtext 

The text of the message. If an insert is necessary within the text of a 
message or at the end of a message, use the following rules: 

# The location of an insert in the middle of a message should be indicated 
by a \,\ 

• If the insert is to be located at the end of a message, indicate it by a ', 
following the message text. 



idl 



id2 



The internal identifier of the message. It may be from one to four 
characters and should not contain a blank, comma, parentheses, or an 
apostrophe. This id is passed to IKJEFF02 in the MTMSGID field of the 
parameter list. 



The internal identifier of a message to be chained to this message. For a 
PUTGET message, the first level message would have an id2 field 
identifying the second level, and the second level message could have an id2 
field to identify another second level, etc. For a PUTLINE, WTO, or 
write-to-programmer message, the second level message would have an id2 
field identifying the first level. 
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For an example of the coding involved for a CSECT containing the IKJTSMSG 
macro, see Figure 8-2. The example shows how a message module can be created 
for a SUBMIT command, using the IKJTSMSG macro. 

• Message IKJ56250I is a single level PUTLINE message with one insert. 

• Message IKJ56251I is a PUTLINE message with two levels. 

• Message IKJ56252A is a PUTGET message with two levels. 

• Message IKJ56253I is a PUTLINE message with an insert at the end of the 
text. 

• The IKJTSMSG macro with no operands is required to indicate the end of 
the message CSECT. 
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Figure 8-2. An Example of an IKJTSMSG Macro Instruction 
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Chapter 9. Attention Interruption Handling — The ST AX Service 
Routine 



The ST AX service routine creates the control blocks and queues necessary for the 
system to recognize and schedule user exits due to attention interruptions. Your 
terminal monitor program, your command processors, or the problem program 
provide the address of an attention exit to the ST AX service routine by issuing the 
STAX macro instruction. You should provide attention exit routines within the 
terminal monitor program and any command processors that accept 
subcommands. Simple command or subcommand procedures should not issue a 
STAX macro instruction unless the STAX routine specified by the TMP or the 
calling command processor cannot process an attention interruption adequately. 

The STAX service routine may be invoked in either 24- or 31 -bit addressing 
mode. The attention exit routine receives control in the same addressing mode in 
which the respective STAX macro is issued. 

With the exception of the TPUT ASID buffers for TCAM, when the user enters 
an attention interruption from the terminal, the TGET, TPUT, and TPG buffers 
are flushed. Any data contained in these buffers is lost. If the user then attempts 
to continue processing from the point of interruption, he may have lost an input 
or an output record, or an output message from the system. 

Attention processing gives the user the ability to specify exit routines that receive 
control asynchronously when the attention key is struck or when an interruption 
occurs as a result of the simulated attention facility (ST ATTN macro). The 
mechanism used to request attention exits is the STAX macro. When the STAX 
macro is issued, a TAXE (terminal attention exit element) is created and placed 
on a queue. The TAXE queue is ordered according to the attention level, and the 
attention level determines the order in which the attention exits are given control. 
If the ATTENTION key is struck once, the first level attention exit is given 
control. If the key is struck twice, the second level attention exit is given control. 
When placing a TAXE on the TAXE queue, two rules apply: 

1 . An attention exit routine for a task will always occupy a higher attention level 
than the attention exit of any of its subtasks. 

2. The attention exit routine is placed at the lowest possible attention level, 
without violating the first rule. 

In other words, the placement at an attention level is determined by the position 
of the task in the subtask queue relative to the position of the other tasks creating 
attention exits. The lower the subtask the lower the attention level assigned. The 
subtask queue is considered to be the mother-daughter queue only. If for any 
reason a complex task structure is created that would have a mother task with 
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multiple daughter tasks, then the order in which the daughters issue ST AX 
macros must be synchronized in order to ensure predictability from day to day. 
Note that the order in which the daughters issue ST AX macros, not the order in 
which the daughters are attached, determines the order in which the associated 
TAXEs are placed on the TAXE queue. 

If a task has issued multiple ST AX macros, the order in which the associated 
TAXE is placed on the TAXE queue is determined by the second rule. 

Attention levels can change during execution of the session for three reasons: 

1. A task has issued ST AX and its daughter then issues ST AX. In this case the 
attention exit for the first task would have an attention level of one until its 
subtask had issued ST AX. The daughter task would then have an attention 
level of one and the original task would have a level of two. 

2. A task that has established an attention exit environment abnormally 
terminates or exits. When this occurs the TAXEs for that task are freed. The 
remaining TAXEs then assume the new attention level relative to its position 
on the TAXE queue. 

3. The ST AX macro is used to cancel the last attention exit established by a 
task. 

When generating an attention interruption by striking the ATTENTION key, the 
ATTENTION level is recorded by counting the number of times the 
ATTENTION key has been struck. If the number of times the key is struck 
exceeds the number of available attention levels, an "!I" message is sent to the 
terminal. If the attention has been accepted, an "!" message is sent to the 
terminal to indicate that the attention exit is being scheduled. If an attention 
interruption is received while a previously requested (lower attention level) 
attention exit is in the process of being scheduled, the first attention exit is 
canceled and the new attention exit is scheduled. This will be true until control 
has been passed to the user's attention exit. 

Prior to passing control to the attention exit, the task under which the attention 
exit is running will have all its subtasks stopped. Note, however, that if a system 
routine (SVRB on RB chain) is executing for one of the TCBs and has not 
specified ST AX DEFER = NO (see below for expanded explanation), then the 
scheduling of the attention exit will be deferred until the completion of such 
system routines. All SVRBs start execution in a ST AX DEFER = YES state and 
all other RBs start execution in a ST AX DEFER = NO state. Consequently, the 
presence of an SVRB on a TCB's RB chain normally means attention exits will be 
deferred. When the user's attention exit completes processing the subtasks are 
automatically restarted. If, for any reason, the attention routine requires one of 
the subtasks to be restarted, it is the responsibility of the attention exit to restart 
the task through the use of the status start facility. If the subtasks should not be 
restarted, it is the responsibility of the attention exit to use the status stop facility 
to ensure that the subtasks will not become dispatchable when the attention exit 
completes processing. See Supervisor Services and Macro Instructions for 
additional information. 
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The attention level at which the attention exit is running and all of the lower 
attention levels are considered unavailable as soon as scheduling of the exit takes 
place. Therefore, once the attention scheduling has begun, only higher attention 
levels are available for use until the attention exit completes processing. 

You can use the ST AX macro not only to specify and cancel attention exits, but 
also to defer the dispatching of attention exits. The DEFER operand of ST AX 
can be specified to set an indicator that will postpone the dispatching of attention 
exits for a TCB and all of the TCBs above it on the mother-daughter TCB chain. 
When ST AX with the DEFER = YES option is specified, a bit in the RB that 
represents the issuer's routine is set (or reset). The indicator in the TCB, which 
allows or defers the dispatching of attention exits, is set equal to the result of 
ORing all of these bits in the RBs on the TCB RB chain. When the TCB defer 
indicator is off for a TCB and all of its subtasks, then attention exits will be 
dispatched. If the defer indicator is on for a TCB or any of its subtasks, then 
attention exits will be deferred until the defer indicator(s) for the TCB and all of 
its subtasks are off. When an attention exit can once again be dispatched, the 
DEFER = NO operand can be used to enable it to be dispatched. 

The deferral bit setting of a routine (RB) can be changed or propagated to other 
routines (RBs) which are used by the original RB. There are three cases to be 
considered. 

1. A new RB is created and placed on the RB queue along with the original RB. 
This can occur if the original RB issues a LINK. In this situation, the routine 
that has been linked maintains its own deferral bit setting. The deferral bit 
setting of the original RB is not passed to the new RB, nor is the deferral bit 
setting of the new RB passed back to the original RB. 

2. A new RB is created and placed on the RB queue and the original RB is 
destroyed. This can occur if the original RB issues an XCTL macro. The 
routine receiving control under the new RB receives the deferral bit setting of 
the original RB. 

3. No new RB is created but control is passed to a routine running under the 
original RB. This can occur if the original RB issues a CALL or LOAD 
macro. The called or loaded routine runs under the original RB. If the called 
or loaded routine issues a STAX macro instruction with the DEFER option, 
then the deferral bit setting is changed for the original RB. 

Note: Tasks within a tree structure being stopped for the attention exit 
scheduling will be stopped in an indeterminate order when any are deferring 
attention exits. As a result, care must be taken to control intertask dependencies 
and dependencies on scheduling attention exits. Failure to do so may result in an 
intertask deadlock that can only be relieved by canceling the TSO user. 
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Specifying a Terminal Attention Exit — The STAX Macro 
Instruction 

Use the STAX macro instruction to specify the address of an attention exit 
routine that is to be given control asynchronously when a user strikes the 
attention key or when a simulated attention is specified. (See the ST ATTN macro 
instruction for a description of the simulated attention function.) 

The STAX macro instruction can also be used to cancel the last attention exit 
routine established by the task. To do this, specify the STAX macro instruction 
without any operands. 

The STAX macro instruction is used only in a time sharing environment. When a 
task other than a TSO user issues the STAX macro, no action is taken. In 
addition, attention exits can be established only for time sharing tasks operating 
in the foreground. 

The system routines that process attention handling require that the STAX 
parameter list remain unchanged for the life of the program. Because the 
expansion of the STAX parameter list is usually located in an area that is reusable 
by the active program, you should either code the necessary protection to prevent 
overlays or you should make a copy of the parameter list in an area that is 
non-reusable. 

Issue the STAX macro instruction to provide the information required by the 
STAX service routine. The STAX macro may be issued in 24- or 31 -bit 
addressing mode. An attention exit routine receives control in the same 
addressing mode in which the STAX macro is issued. 

The STAX macro instruction has a list, an execute, and a standard form. 

The list form of the STAX macro instruction (MF = L) generates a STAX 
parameter list. The execute form of the STAX macro instruction 
(MF = E,address) completes or modifies that list and passes its address to the 
STAX service routine. The standard form does not require you to specify MF = L 
or MF = E. 

Figure 9-1 shows the format of the list and execute forms of the STAX macro 
instruction; each of the operands is explained following the figure. Appendix A 
describes the notation used to define macro instructions. 




["exit address [ ,OBUF=( output buffer address, size) ]1 
[ [, IBUF= ( input buffer address, size ) ] J 



l^,USADDR=user address] 

, replace= j yesm 

,defer=IyesI| 
\no )\ 

=L \ 

(E, address )( 



VMF= 



Figure 9-1. The STAX Macro Instruction — List and Execute Forms 
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Note: When the ST AX macro is issued in 31 -bit addressing mode, exit addr and 
USADDR may reside above 16 megabytes. All other input must reside below 16 
megabytes. 

exit address 

Specify the entry point of the routine to be given control when an attention 
interruption is received. You must specify the exit address in both the list 
and the execute forms of the ST AX macro instruction when you are 
establishing an attention interruption handling exit. 

You need not specify an exit address if you are using the DEFER operand 
as long as you code no other operands (except the MF operand). If you 
exclude the exit address and code no other operands, the ST AX service 
routine cancels the previous attention exit established by the task issuing this 
STAX macro instruction. 

OBUF = (output buffer address,output buffer size) 

Output buffer address - Supply the address of a buffer you have obtained 
and initiated with the message to be put out to the terminal user who 
entered the attention interruption. This message may identify the exit 
routine and request information from the terminal user. It is sent to the 
terminal before the attention exit routine is given control. 

Output buffer size - Indicate the number of characters in the output buffer. 
The size may range from to 32,767 (2 15 -1) inclusive. 

IBUF = (input buffer address,input buffer size) 

Input buffer address - Supply the address of a buffer you have obtained to 
receive responses from the terminal user. The attention exit routine is not 
given control until the STAX service routine has placed the terminal user's 
reply into this buffer. 

Input buffer size - Indicate the number of bytes you have provided as an 
input buffer. The size may range from to 32,767 (2 15 -1) inclusive. 

USADDR = (user address) 

The user address is a pointer to any information you want passed to your 
attention handling exit routine when it is given control. 

REPLACE = YESorNO 

YES indicates that the attention exit specified by this STAX macro 
instruction replaces any attention exit specified by a STAX macro 
instruction previously issued by this task. YES is the default value. 
REPLACE implies establishing a new attention exit routine for the task, if 
no previous attention exit has been established. 

NO indicates that this attention exit be established as a new attention exit 
for this task, in addition to any that have been previously established for 
this task. 

DEFER=YESorNO 

The DEFER operand is optional. If the DEFER operand is coded in the 
STAX macro instruction, the option you request (YES or NO) applies to all 
tasks within the task chain in which the macro instruction was issued. Any 



Chapter 9. Attention Interruption Handling -- The STAX Service Routine 9-5 



task may issue the ST AX macro instruction to specify DEFER = YES or 
NO; the issuing task need not itself have provided an attention exit routine. 
If the DEFER operand is not coded in the macro instruction, no action is 
taken by the STAX service routine regarding the deferral of attention exits. 

YES indicates that any attention interruptions received are to be queued 
and are not to be processed until another STAX macro instruction is 
executed specifying DEFER = NO, or until the program that issued the 
STAX with the DEFER = YES terminates. 

NO indicates that the defer option is being canceled. Any attention 
interruptions received while the defer option was in effect will be processed. 
If the DEFER operand is omitted, the control program leaves the deferral 
status unchanged. 

Be aware that if a program issues a STAX macro instruction specifying 
DEFER = YES, the program can get into a situation where an attention 
interruption cannot be received from the terminal. If your program enters a 
loop or an unending wait before it has issued a STAX macro instruction 
specifying DEFER = NO, you cannot regain control at the terminal by 
entering an attention interruption. 

You need not specify an exit address in a STAX macro instruction issued 
only to change deferral status. 

MF = L 

This specifies the list form of the STAX macro instruction. It generates a 
STAX parameter list. 

MF = (E,address) 

This specifies the execute form of the STAX macro instruction. It 
completes or modifies the STAX parameter list and passes the address of 
the parameter list to the STAX service routine. Place the address of the 
STAX parameter list (the address of the list form of the STAX macro 
instruction) into a register and specify that register number within 
parentheses. 

You can place each of the required address and size parameters into registers and 
specify those registers, within parentheses, in the STAX macro instruction. 
Figure 9-2 shows how an execute form of the STAX macro instruction may look 
if you load all the required parameters into registers. 



STAX 



(2) ,IBUF=( (3) , (4) ) ,OBUF=( (5) , (6) ) ,USADDR=(7) ,MF=(E, (1) ) 



Figure 9-2. Using Registers in the STAX Macro Instruction 
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The ST AX Parameter List 



When the list form of the ST AX macro instruction expands, it builds the ST AX 
parameter list. The list form of the macro instruction initializes this ST AX 
parameter list according to the operands you have coded. The execute form of 
the ST AX macro instruction modifies the ST AX parameter list and passes its 
address to the ST AX service routine. 

Figure 9-3 describes the contents of the ST AX parameter list for MVS/370 and 
MVS/XA. Figure 9-4 describes the contents of the ST AX parameter list 
extension for MVS/XA. 



Number 






of Bytes 


Field 


Contents or Meaning 


4 


STXEXIT 


Contains the address of the attention exit routine to receive control in 
response to an attention interruption. This is the address you supplied 
as the exit address operand on the ST AX macro instruction. 


2 


STXISIZ 


Contains a binary number representing the size of the input buffer you 
provided as the IBUF operand on the STAX macro instruction. The 
maximum buffer size is 32,767 bytes. 


2 


STXOSIZ 


Contains a binary number representing the size of the output buffer 
you provided as the OBUF operand on the STAX macro instruction. 
The maximum buffer size is 32,767 bytes. 


4 


STXOBUF 


Contains the address of the output buffer you provided as the OBUF 
operand on the STAX macro instruction. 


4 


STXIBUF 


Contains the address of the input buffer you provided as the IBUF 
operand on the STAX macro instruction. 


1 


STXOPTS 


STAX option flags. 




.0 


REPLACE = YES 




.1 


REPLACE = NO 




..1 


Defer attention interruption processing, that is DEFER = YES. 




...1 .... 


Cancel the deferral of attention interruption processing, that is 
DEFER = NO. 




.... 1... 


Indicates that the CLIST attention counter should be increased by 1 . 




1.. 


Indicates that the CLIST attention counter should be decreased by 1. 




1. 


In MVS/XA, indicates that STXFNUM contains a format number. In 
MVS/370, this bit is zero. 




X X 


Reserved bits. 


3 


STXUSER 


Address of user's parameter list for MVS/370 format 



Figure 9-3. The STAX Parameter List 



Number 
of Bytes 


Field 


Contents or Meaning 


1 

2 
4 


STXFNUM 
1 

STXNUSER 


STAX format flags. 

Contains a format number indicating that the MVS/XA version of the 
STAX parameter list is used. (MVS/XA only) 

Reserved bytes. (MVS/XA only) 

Contains the address of the parameters you want passed to your 
attention handling exit routine when it is given control. This is the 
address you supplied as the USADDR operand on the STAX macro 
instruction. (MVS/XA only) 



Figure 9-4. The STAX Parameter List Extension for MVS/XA 
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Coding Example of the ST AX Macro Instruction 



The coding example shown in Figure 9-5 uses the list and the execute forms of 
the ST AX macro instruction to set up an attention handling exit. The OBUF 
operand provides a message to be written to the terminal when the attention 
interruption is received, and the IBUF operand provides space for an input buffer. 
This example does not code the REPLACE operand in the macro instruction; 
YES is the default value. The attention handling exit established by this 
execution of the ST AX macro instruction replaces the previous attention handling 
exit established for this task. 
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Figure 9-5. Coding Example - STAX Macro Instruction 
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Return Codes from the ST AX Service Routine 



Control is returned to the instruction following the ST AX macro instruction. 
When control is returned, register 1 will contain the address of the user parameter 
list provided for the previous exit for this task or will contain zero. The register 
will contain zero if this is the first ST AX issued for this task, a ST AX with a 
cancel option, or a ST AX with only the DEFER option. If an error was detected 
(return code 8), then the contents of register 1 will be the same as it was at entry. 
Register 15 will contain one of the following return codes: 

Code Meaning 

The ST AX service routine successfully completed the function you requested. 

4 Deferral of attention exits has already been requested and is presently in effect. Any other 

operands you specified in the STAX macro instruction have been processed successfully. 

8 Invalid user of DEFER option (asynchronous exit routine). 

If any combination of parameters or the parameters themselves are invalid, an 
ABEND will be issued. 

The types of errors that will cause an ABEND are: 

• Both DEFER = YES and DEFER = NO are specified. 

• Invalid input buffer address (storage not in same key as user's TCB). 

• Invalid buffer size (input or output). 
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Chapter 10. Dynamic Allocation of Data Sets - The Dynamic 
Allocation Interface Routine (DAIR) 



Considerations 



Dynamic allocation routines allocate, free, concatenate, and deconcatenate data 
sets dynamically; that is, during problem program execution. With TSO, dynamic 
allocation permits the terminal monitor program, command processors, and other 
problem programs executing in the foreground region to allocate data sets after 
LOGON and free them before LOGOFF. 

For a complete discussion of dynamic allocation, see SPL: System Macros and 
Facilities. 

The dynamic allocation routines may be accessed by TSO directly or through the 
dynamic allocation interface routine (DAIR). Though its use is not recommended 
because of reduced functions and additional system overhead, DAIR can be used 
to obtain information about a data set and, if necessary, invoke dynamic 
allocation routines to perform the requested function. 

You can use DAIR to perform the following functions: 

• Obtain the current status of a data set 

• Allocate a data set 

• Free a data set 

• Concatenate data sets 

• Deconcatenate data sets 

• Build a list of attributes (DCB parameters) to be assigned to data sets 

• Delete a list of attributes 



The user must correctly initialize the DAIR parameter block (DAPB) before 
calling DAIR. Unused fields should be zeroed or blanked (if character items). 

Specifying the data set name and the member name for DAIR entry code X'08' 
causes the data set to be allocated but no check is done to see if the member 
exists. To verify that the member really exists: 

• Allocate the data set with the member name using DAIR entry code X'08'. 

• Open the data set with DSORG = PO, MACRF = R. 

• Issue BLDL for the member. (The BLDL return code will indicate whether 
the member is there or not.) 
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• Close the data set. 

# If BLDL indicates that the member does not exist, unallocate the data set 
using ddname and DAIR entry code X' 18'. 



Using DAIR 



Invoke the DAIR service routine via a CALLTSSR macro instruction, specifying 
the entry point IKJDAIR in load module IKJDAIR. 

The DAIR service routine may be invoked in either 24- or 31 -bit addressing 
mode. When invoked in 31 -bit addressing mode, DAIR may be passed input 
above 16 megabytes. 

The control block structure required by the DAIR service routine is shown in 
Figure 10-1. Note that the DAIR parameter block (DAPB) is a variable-size 
block; the block size depends upon the function requested by the calling routine. 
That function is indicated to the DAIR service routine by the code in the first two 
bytes of the DAIR parameter block. (See "Processing Terminal Requests ~ The 
TSO Service Routines" for a description of the CALLTSSR macro and a list of 
IBM-supplied mapping macros for parameter lists.) 
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CALLTSSR 




DAPL 



DAPB 



Entry Code 




DAIR 



Figure 10-1. Control Blocks Passed to DAIR 
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The DAIR Parameter List (DAPL) 



At entry to DAIR, register 1 must point to a DAIR parameter list that you have 
built. Figure 10-2 shows the format of the DAPL. The addresses of the user 
profile table, environment control table, and protected step control block may be 
obtained from the command processor parameter list (CPPL) that the TMP 
passes to your command processor. Additional information on the address and 
creation of the user profile table, environment control table, and protected step 
control block is shown in Figure 7-2 (the command processor parameter list). 



Number 
of Bytes 


Field 


Contents or Meaning 


4 
4 
4 

4 
4 


DAPLUPT 
DAPLECT 
DAPLECB 

DAPLPSCB 
DAPLDAPB 


The address of the user profile table. 

The address of the environment control table. 

The address of the calling program's event control block. The ECB is 
one word of real storage declared and initialized to zero by the calling 
routine. 

The address of the protected step control block. 

The address of the DAIR parameter block, created by the calling 
routine. 



Figure 10-2. Format of the DAIR Parameter List (DAPL) 
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The DAIR Parameter Block (DAPB) 



The fifth word of the DAIR parameter list must contain a pointer to a DAIR 
parameter block built by the calling routine. 

It is a variable-size parameter block that contains, in the first two bytes, an entry 
code that defines the operation requested by the calling routine. The remaining 
bytes contain other information required by DAIR to perform the requested 
function. Figure 10-3 is a list of the DAIR entry codes and the functions 
requested by those codes. 



Entry 

Code Function Performed by DAIR 

X'00' Test if a given DSNAME or DDNAME is currently allocated to the caller. 

X'04' Test if a given DSNAME is currently allocated to the caller, or is in system catalog. 

X'08' Allocate a data set by DSNAME. 

X'OC Concatenate data sets by DDNAME. 

X'10' Deconcatenate data sets by DDNAME. 

X'14' Search the system catalog for all qualifiers for a DSNAME. (The DSNAME alone 
represents an unqualified index entry.) 

X'18' Free a data set. 

X'lC Allocate a DDNAME to a terminal. 

X'24' Allocate a data set by DDNAME or DSNAME. 

X'28' Perform a list of operations. 

X'2C Mark data sets as not in use. 

X'30' Allocate a SYSOUT data set. 

X'34' Associate DCB parameter with a specified name for use with subsequent allocations. 



Figure 10-3. DAIR Entry Codes and Their Functions 

The DAIR parameter blocks have the formats shown in the following tables. The 
formats of the blocks depend upon the function requested by the calling routine. 
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Code X'OO' - Determine if DDNAME or DSNAME Allocated 



Build the DAIR parameter block shown in Figure 10-4 to request that DAIR 
determine whether or not the specified DSNAME or DDNAME is allocated. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 


DA00CD 


Entry code X'0000' 


2 


DA00FLG 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 




Byte 1 
0000 .... 
... 1... 

1.. 

1. 

1 


Reserved. Set to zero. 

DSNAME or DDNAME is permanently allocated. 

DDNAME is a DYNAM. 

The DSNAME is currently allocated. 

The DDNAME is currently allocated to the terminal. 




Byte 2 
0000 0000 


Reserved. Set to zero. 


4 


DA00PDSN 


Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46 byte field with the following format: 

The first two bytes contain the length, in bytes of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified, and padded to the 
right with blanks. 


8 


DA00DDN 


Contains the DDNAME for the requested data set. If a DSNAME is 
present, the DAIR service routine ignores the contents of this field. 


1 


DA00CTL 


A flag field: 




00.0 0000 
..1 


Reserved bits. Set to zero. 
Prefix userid to DSNAME. 


2 




Reserved bytes; set these bytes to zero. 


1 


DA00DSO 


A flag field. These flags describe the organization of the data. They are 
returned to the calling routine by the DAIR service routine. 




1 

.1 

..1 

...1 .... 
.... 1... 

1.. 

1. 

1 


Indexed sequential organization 

Physical sequential organization 

Direct organization 

BTAM or QTAM line group 

QTAM direct access message queue 

QTAM problem program message queue 

Partitioned organization 

Unmovable 



Figure 10-4. DAIR Parameter Block » Entry Code X'00' 

After DAIR searches the data set entry for the fully qualified data set name, 
register 1 5 contains one of the following DAIR return codes: 

0, 4, 52 

See "Return Codes from DAIR" for return code meanings. 
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Code X'04' - Determine if DSNAME Allocated or in System Catalog 



Build the DAIR parameter block shown in Figure 10-5 to request that DAIR 
determine whether or not the specified DSNAME is allocated. DAIR also 
searches the system catalog to find an entry for the DSNAME. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 


DA04CD 


Entry code X'0004' 


2 


DA04FLG 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 




Byte 1 
0000 0..0 

1„ 

1. 


Reserved bits. Set to zero. 

DAIR found the DSNAME in the catalog. 

The DSNAME is currently allocated. 




Byte 2 
0000 0000 


Reserved. Set to zero. 


2 




Reserved. Set to zero. 


2 


DA04CTRC 


These two bytes will contain an error code from the catalog 
management routines if an error was encountered by catalog 
management. 


4 


DA04PDSN 


Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46-byte field with the following format: 

The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified, and padded to the 
right with blanks. 


1 


DA04CTL 


A flag field: 




00.0 0000 
..1 


Reserved bits. Set to zero. 
Prefix userid to DSNAME. 


2 




Reserved bytes; set these bytes to zero. 


1 


DA04DSO 


A flag field. These flags are set by the DAIR service routine; they 
describe the organization of the data set to the calling routine. These 
flags are returned only if the data set is currently allocated. 




1 

.1 

..1 

...1 .... 
.... 1... 

1.. 

1. 

1 


Indexed sequential organization 
Physical sequential organization 
Direct organization 
BTAM or QTAM line group 
QTAM direct access message queue 
QTAM problem program message queue 
Partitioned organization 
Unmovable 



Figure 10-5. DAIR Parameter Block - Entry Code X'04' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 8, 52 

See "Return Codes from DAIR" later in this section for return code meanings. 
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Code XW - Allocate a Data Set by DSNAME 



Build the DAIR parameter block shown in Figure 10-6 to request that DAIR 
allocate a data set. The exact action taken by DAIR depends upon the presence 
of the optional fields and the setting of bits in the control byte. 

If the data set is new and you specify DSNAME, (NEW, CATLG) the data set is 
cataloged upon successful allocation. This is the only time a data set will be 
cataloged at allocation time. If the catalog attempt is unsuccessful, the data set is 
freed. If the proper indices are not present, the indices are built. 

To allocate a utility data set use DAIR code X'08' and use a DSNAME of the 
form &name. If the &name is found allocated, that data set is used. If the 
&name is not found, a new data set is allocated. 

To supply DCB information, provide the name of an attribute list that has been 
defined previously by a X'34' entry into DAIR. 

When setting disposition in a parameter list, only one bit should be on. 

The DAIR parameter block required for entry code X'08' has the format shown 
in Figure 10-6. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 


DA08CD 


Entry code X'0008' 


.. 2 


DA08FLG 
Byte 1 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 




1 


The data set is allocated but a secondary error occurred. Register 15 
contains an error code. 




.000 0000 


Reserved bits. Set to zero. 




Byte 2 


Reserved. Set to zero. 


2 


DA08DARC 


This field contains the error code, if any, returned from the dynamic 
allocation routines. (See "Return Codes from Dynamic Allocation.") 


2 


DA08CTRC 


This field contains the error code, if any, returned from catalog 
management routines. (See "Return Codes from DAIR.") 


4 


DA08PDSN 


Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46 byte field with the following format: 

The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified and padded to the 
right with blanks. If this field (DA08PDSN) is zero, the system 
generates a data set name unless bit 5 in DA08CTL is on, in which case 
a DUMMY data set is allocated. The system also generates a name if 
the DA08PDSN field points to a DSNAME buffer which has a length 
of 44, is initialized to blanks, and bit 5 in DA08CTL is off. 


8 


DA08DDN 


This field contains the DDNAME for the data set. If a specific 
DDNAME is not required, fill this field with eight blanks; DAIR will 
place in this field the DDNAME to which the data set is allocated. 



Figure 10-6 (Part 1 of 3). DAIR Parameter Block - Entry Code X'08' 
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Number 
of Bytes 



Field 



Contents or Meaning 



DA08UNIT 



DA08SER 



DA08BLK 



DA08PQTY 



DA08SQTY 



DA08DQTY 



DA08MNM 



DA08PSWD 



DA08DSP1 

0000 .... 
.... 1... 

1.. 

1. 

1 



This is an eight-byte field containing an esoteric group name, a generic 
group name, or a specific device address (in EBCDIC). If the unit 
information is less than eight characters, it must be padded to the right 
with blanks. If no information is to be provided, the field must be 
blank. In this case, DAIR will obtain information from the protected 
step control block. If there is no unit information in the PSCB, then a 
default of all direct access devices is used. The specified unit 
information will be ignored if volume information is obtained from the 
catalog, unless the unit specification is a subset of that obtained from 
the catalog. In this case the specified unit information will override the 
returned information. 

Serial number desired. Only the first six bytes are significant. If the 
serial number is less than six bytes, it must be padded to the right with 
blanks. If the serial number is omitted, the entire field must contain 
blanks. In this case the following is done: if the data set is a new data 
set, the system determines the volume to be used for the data set based 
on the unit information. If the data set already exists, volume and unit 
information are obtained from the catalog. If the information is not 
found in the catalog, the allocation request is denied. 

This is a four-byte field used as follows: if the data set is a new data 
set and bit in DA08CTL is off and bit 1 in DA08CTL is on, this field 
is used with DA08PQTY to determine the amount of direct access 
space to be allocated for the data set. If bit 6 of DA08CTL is off, the 
field is also used as DCB blocksize specification. The value for 
blocksize must be placed in the low-order two bytes, and the high-order 
bytes must be zero. 

Primary space quantity desired. The high-order byte must be set to 
zero and the low-order three bytes should contain the space quantity 
required. If the quantity is omitted, the entire field must be set to zero. 
In the case of new direct access data sets, primary and secondary spaceu 
and type of space are defaulted. Directory quantity is used if specified 
in DA08DQTY. 

Secondary space quantity desired. The high-order byte must be set to 
zero; the low-order three bytes should contain the secondary space 
quantity required. If the quantity is omitted, the entire field must be 
set to zero. 

Directory quantity required. The high-order byte must be set to zero; 
the low-order three bytes contain the number of directory blocks 
desired. If the quantity is omitted, the entire field must be set to zero. 

Contains a member name of a partitioned data set. If the name has 
less than eight characters, pad it to the right with blanks. If the name 
is omitted, the entire field must contain blanks. 

Contains the password for the data set. If the password has less than 
eight characters, pad it to the right with blanks. If the password is 
omitted, the entire field must contain blanks. 

Flag byte. Set the following bits to indicate the status of the data set: 

Reserved. Set these bits to zero. 

SHR 

NEW 

MOD 

OLD 

If this byte is zero, OLD is assumed. NEW or MOD is required if 
DSNAME is omitted. 



Figure 10-6 (Part 2 of 3). DAIR Parameter Block - Entry Code X'08' 



Chapter 10. Dynamic Allocation of Data Sets - The Dynamic Allocation Interface Routine (DAIR) 10-9 



Number 
of Bytes 


Field 


Contents or Meaning 


1 


DA08DPS2 


Flag byte. Set the following bits to indicate the normal disposition of 
the data set: 




0000 .... 
.... 1... 

1.. 

1. 

1 


Reserved bits. Set them to zero. 

KEEP 

DELETE 

CATLG 

UNCATLG 

If this byte is zero, it is defaulted as follows: if DA08DSP1 is NEW, 
DELETE is used; otherwise, KEEP is used. 


1 


DA08DPS3 


Flag byte. Set the following bits to indicate the abnormal disposition 
of the data set: 




0000 .... 
.... 1... 

1.. 

1. 

1 


Reserved bits. Set them to zero. 

KEEP 

DELETE 

CATLG 

UNCATLG 

If this byte is zero, DA08DPS2 will be used. 


1 


DA08CTL 


Flag byte. These flags indicate to the DAIR service routine what 
operations are to be performed: 




XX 


Indicate the type of units desired for the space parameters, as follows: 




01 


Units are in average block length. 




10 


Units are in tracks (TRKS). 




11 


Units are in cylinders (CYLS). 




..1 


Prefix userid to DSNAME. 




...1 .... 


RLSE is desired. 




.... 1... 


The data set is to be permanently allocated; it is not to be freed until 
specifically requested. 




1.. 


A DUMMY data set is desired. 




1. 


Attribute list name supplied. 







Reserved bit; set to zero. 


3 




Reserved bytes; set them to zero. 


1 


DA08DSO 


A flag field. These flags are set by the DAIR service routine; they 
describe the organization of the data set to the calling routine. 




1 

.1 

..1 

...1 .... 
.... 1... 

1.. 

1. 

1 


Indexed sequential organization 

Physical sequential organization 

Direct organization 

BTAM or QTAM line group 

QTAM direct access message queue 

QTAM problem program message queue 

Partitioned organization 

Unmovable 


8 


DA08ALN 


Attribute list name, or a DD name from which DCB attributes should 
be copied (as in a JCL DCB reference). If the name is less than 8 
characters, it should be padded to the right with blanks. 



Figure 10-6 (Part 3 of 3). DAIR Parameter Block -- Entry Code X'08' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 8, 12, 16, 20, 28, 32, 44, 52 

See the topic "Return Codes from DAIR" for return code meanings. 
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Code X'OC - Concatenate the Specified DDNAMES 



Build the DAIR parameter block shown in Figure 10-7 to request that DAIR 
concatenate data sets. The DDNAMES listed in the DAIR parameter block are 
to be concatenated in the order in which they appear. All data sets listed by 
DDNAME in the DAIR parameter block must be currently allocated. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 


DAOCCD 


Entry code X'OOOC 


2 


DAOCFLG 


Reserved. Set this field to zero. 


2 


DAOCDARC 


This field contains the error code, if any, returned from the dynamic 
allocation routines. (See "Return Codes from Dynamic Allocation.") 


2 




Reserved field. Set this field to zero. 


2 


DAOCNUMB 


Place in this field the number of data sets to be concatenated. 


2 




Reserved. Set this field to zero. 


8 


DAOCDDN 


Place in this field the DDNAME of the first data set to be 
concatenated. This field is repeated for each DDNAME to be 
concatenated. 



Figure 10-7. DAIR Parameter Block ~ Entry Code X'OC 

After attempting the requested function, DAIR returns one of the following codes 
in register 15. 

0, 4, 12, 52 

See "Return Codes from DAIR" for return code meanings. 

Code X'10' - Deconcatenate the Indicated DDNAME 

Build the DAIR parameter block shown in Figure 10-8 to request that DAIR 
deconcatenate a data set. The DDNAME specified within the DAIR parameter 
block has been previously concatenated and is now to be deconcatenated. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 
2 
2 

2 
8 


DAIOCD 

DAIOFLG 

DAIODARC 

DAIODDN 


Entry code X'0010' 

Reserved. Set this field to zero. 

This field contains the error code, if any, returned from the dynamic 
allocation routines. (See "Return Codes from Dynamic Allocation.") 

Reserved field. Set this field to zero. 

Place in this field the DDNAME of the data set to be deconcatenated. 



Figure 10-8. DAIR Parameter Block - Entry Code X'10' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 12, 52 

See "Return Codes from DAIR" for return code meanings. 
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Code X'14' - Return Qualifiers for the Specified DSNAME 



Build the DAIR parameter block shown in Figure 10-9 to request that DAIR 
return all qualifiers for the DSNAME specified. 

You must also provide the return area pointed to by the third word of the DAIR 
parameter block. If the area you provide is larger than needed for all returned 
information, the remaining bytes in the area are set to zero by DAIR. If the area 
is smaller than required, it is filled to its limit, and the return code specifies this 
condition. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 


DA14CD 


Entry code X'0014' 


2 


DA14FLG 


Reserved. Set this field to zero. 


4 


DA14PDSN 


Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46 byte field with the following format: 

The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified and padded to the 
right with blanks. DSNAME alone represents an unqualified index 
entry. 


4 


DA14PRET 


Place in this field the address of the return area in which DAIR is to 
place the qualifiers found for the DSNAME. Place the length of the 
return area in the first two bytes of the return area. Set the next two 
bytes in the return area to zero. DAIR returns each of the qualifiers it 
finds in two fullwords of storage beginning at the first word (offset 0) 
within the return area. 


1 


DA14CTL 


A flag field. 




Byte 1 
00.0 0000 
..1 


Reserved bits; set them to zero. 
Prefix userid to DSNAME. 


3 




Reserved bytes. Set this field to zero. 



Figure 10-9. DAIR Parameter Block -- Entry Code X'14' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 36, 40 

See "Return Codes from DAIR" for return code meanings. 



Code X'18' - Free the Specified Data Set 



Build the DAIR parameter block shown in Figure 10-10 to request that DAIR 
free a data set. The data set name represented by DSNAME is to be freed. If 
no DSNAME is given, the data set associated with the DDNAME is freed. If 
both DDNAME and DSNAME are given, DAIR ignores the DDNAME. 

If the specified DSNAME is allocated several times to the user, all such 
allocations are freed. 

When setting disposition in a parameter list, only one bit should be on. 
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Number 
of Bytes 


Field 


Contents or Meaning 


2 


DA18CD 


Entry code X'0018' 


2 


DA18FLG 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meanings: 




Byte 1 
1 


The data set is freed but a secondary error occurred. Register 15 
contains zero and the error information is in DAI 8D ARC. 




.000 0000 


Reserved bits. Set to zero. 




Byte 2 


Reserved. Set to zero. 


2 


DA18DARC 


This field contains the error code, if any, returned from the dynamic 
allocation routines. (See "Return Codes from Dynamic Allocation.") 


2 


DA18CTRC 


This field contains the error code, if any, returned from catalog 
management routines. (See "Return Codes from DAIR.") 


4 


DA18PDSN 


Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46-byte field with the following format: 

The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified and padded to the 
right with blanks. This field is zero if the DSNAME is not specified. 


8 


DA18DDN 


Place in this field the DDNAME of the data set to be freed, or blanks. 
If DSNAME is specified, this field is ignored. 


8 


DA18MNM 


Contains the member name of a partitioned data set. If the name has 
less than eight characters, pad it to the right with blanks. If the name 
is omitted, the entire field must contain blanks. 


2 


DA18SCLS 


SYSOUT class. The output class may be A-Z or 0-9 in the first byte. 
The second byte in the field is ignored. If SYSOUT is not specified, 
the first byte of this field must contain zeros or blanks. 


1 


DA18DPS2 


Flag byte. Set the following bits to override the normal disposition of 
the data set: 




0000 .... 
.... 1... 

1.. 

1. 

1 


Reserved bits. Set them to zero. 

KEEP 

DELETE 

CATLG 

UNCATLG 

If the disposition specified at allocation is to be used, this field must 
contain zero. 


1 


DA18CTL 


Flag byte. These flags indicate to the DAIR service routine what 
operations are to be performed: 




..1 


Prefix userid to DSNAME (requires DA18PDSN data be available). 




00.. 0000 


Reserved bits: set them to zero. 




...1 .... 


If this bit is on, permanently allocated data sets are unallocated. If the 
bit is off, the data set will be marked "not in use," if it is permanently 
allocated. 


8 




Reserved bytes; set this field to hexadecimal zeros. 



Figure 10-10. DAIR Parameter Block - Entry Code X'18' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 12, 24, 28, 52 

See "Return Codes from DAIR" for return code meanings. 
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Code X'lC - Allocate the Specified DDNAME to the Terminal 



Build the DAIR parameter block shown in Figure 10-11 to request that DAIR 
allocate a DDNAME to the terminal. If the DDNAME field is left blank, DAIR 
returns the allocated DDNAME in that field. To supply DCB information, 
provide the name of an attribute list that has been defined previously by a X'34' 
entry into DAIR, or the DDNAME of a currently allocated data set from which 
DCB attributes can be copied (as in a JCL DCB reference). 



Number 
of Bytes 


Field 


Contents or Meaning 


2 


DA1CCD 


Entry code X'OOIC 


2 


DA1CFLG 


Reserved field; set it to zero. 


2 


DAI CD ARC 


This field contains the error code, if any, returned from the dynamic 
allocation routines. (See "Return Codes from Dynamic Allocation.") 


1 




Reserved field; set it to zero. 


1 


DA1CCTL 


Control byte. 




.... 1... 


The data set is to be permanently allocated; it is not to be freed until 
specifically requested. 




1. 


Attribute list name supplied. 




0000 .0.0 


Reserved; set to zero. 


8 


DA1CDDN 


Place in this field the DDNAME for the data set to be allocated to the 
terminal or blanks if the allocated DDNAME should be returned in 
this field. 


8 


DA1CALN 


Attribute list name that has been defined previously by a X'34' entry 
into DAIR, or a DDNAME of a currently allocated data set from 
which DCB attributes can be copied. This field is used only if Bit 6 of 
DA1CCTL is set to one. 



Figure 10-11. DAIR Parameter Block - Entry Code X'lC 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 12, 16, 20, 28, 52 

See "Return Codes from DAIR" later in this section for return code meanings. 

Code X'24' - Allocate a Data Set by DDNAME 

Build the DAIR parameter block shown in Figure 10-12 to request that DAIR 
allocate a data set by DDNAME. 

If DAIR locates the DDNAME you specify and a DSNAME is currently 
associated with it, the associated DSNAME is allocated overriding the DSNAME 
pointed to by the third word of your DAIR parameter block. The DDNAME 
may be found associated with a DUMMY, and if so an indicator is returned but 
no allocation takes place. 

If DAIR cannot allocate by DDNAME, it will give control to code X'08' to 
allocate by DSNAME and will generate a new DDNAME. 

When setting disposition in a parameter list, only one bit should be on. 
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Number 
of Bytes 


Field 


2 


DA24CD 


2 


DA24FLG 




Byte 1 
1 




.... I... 
.000 .000 




Byte 2 


2 


DA24DARC 


2 


DA24CTRC 


4 


DA24PDSN 



Contents or Meaning 



DA24DDN 



DA24UNIT 



DA24SER 



DA24BLK 



DA24PQTY 



Entry code X'0024' 

A flag field set by DAIR before returning to the calling routine, 
flags have the following meaning: 



The 



The data set is allocated but a secondary error occurred. Register 15 
contains an error code. 

DDNAME requested is allocated as DUMMY. 

Reserved bits. Set to zero. 

Reserved. Set to zero. 

This field contains the error code, if any, returned from the dynamic 
allocation routines. (See "Return Codes from Dynamic Allocation.") 

This field contains the error code, if any, returned from catalog 
management routines. (See "Return Codes from DAIR.") 

Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46-byte field with the following format: 

The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified and padded to the 
right with blanks. If the specified DDNAME is used, this field 
(DA24PDSN) is ignored. 

Place here the DDNAME for the data set to be allocated. This 
DDNAME is required. If the specified DDNAME is not allocated, 
then a generated DDNAME will be used with the DSNAME and the 
generated DDNAME will be returned in this field. 

This is an eight-byte field containing an esoteric group name, a generic 
group name, or a specific device address (in EBCDIC). If the unit 
information is less than eight characters, it must be padded to the right 
with blanks. If no information is to be provided, the field must be 
blank. In this case, DAIR will obtain information from the protected 
step control block. If there is no unit information in the PSCB, then a 
default of all direct access devices is used. The specified unit 
information will be ignored if volume information is obtained from the 
catalog, unless the unit specification is a subset of that obtained from 
the catalog. In this case the specified unit information will override the 
returned information. 

Serial number desired. Only the first six bytes are significant. If the 
serial number is less than six bytes, it must be padded to the right with 
blanks. If the serial number is omitted, the entire field must contain 
blanks. In this case, the following is done: 

If the data set is a new data set, the system determines the volume to be 
used for the data set based on the unit information. If the data set 
already exists, volume and unit information are obtained from the 
catalog. If the information is not found in the catalog, the allocation 
request is denied. 

This is a four-byte field used as follows: If the data set is a new data 
set and CONTROL bit is off and bit 1 is on (see below), this field is 
used with PRIMARY SPACE QUANTITY to determine the amount 
of direct access space to be allocated for the data set. If CONTROL 
bit 6 is off, the field is also used as a DCB blocksize specification. The 
value for BLOCKSIZE must be placed in the low-order two bytes. The 
high-order byte must be zero. 

Primary space quantity desired. The high-order byte must be set to 
zero; the low-order three bytes should contain the space quantity 
required. If the quantity is omitted, the entire field must be set to zero. 
In this case for new direct access data sets primary and secondary 
space, and type of space will be defaulted. Directory quantity will be 
used if specified in DA24DQTY. 



Figure 10-12 (Part 1 of 3). DAIR Parameter Block - Entry Code X'24' 
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Number 
of Bytes 


Field 


Contents or Meaning 


4 


DA24SQTY 


Secondary space quantity desired. The high order byte must be set to 
zero; the low order three bytes should contain the secondary space 
quantity required. If the quantity is omitted, the entire field must be 
set to zero. 


4 


DA24DQTY 


Directory quantity required. The high order byte must be set to zero; 
the low order three bytes contain the number of directory blocks 
desired. If the quantity is omitted, the entire field must be set to zero. 


8 


DA24MNM 


Contains a member name of a partitioned data set. If the name has 
less than eight characters, pad it to the right with blanks. If the name 
is omitted, the entire field must contain blanks. 


8 


DA24PSWD 


Contains the password for the data set. If the password has less than 
eight characters, pad it to the right with blanks. If the password is 
omitted, the entire field must contain blanks. 


1 


DA24DSP1 


Flag byte. Set the following bits to indicate the status of the data set: 




0000 .... 
.... 1... 

1.. 

1. 

1 


Reserved. Set these bits to zero. 

SHR 

NEW 

MOD 

OLD 

If this byte is zero, OLD is assumed. 


1 


DA24DPS2 


Flag byte. Set the following bits to indicate the normal disposition of 
the data set: 




0000 .... 
.... 1... 

1.. 

1. 

1 


Reserved bits. Set them to zero. 

KEEP 

DELETE 

CATLG 

UNCATLG 

If this byte is zero, it is defaulted as follows: if DA24DSP1 is new, 
DELETE is used; otherwise KEEP is used. 


1 


DA24DPS3 


Flag byte. Set the following bits to indicate the abnormal disposition 
of the data set: 




0000 .... 
.... I... 

1.. 

1. 

.... ...1 


Reserved bits. Set them to zero. 

KEEP 

DELETE 

CATLG 

UNCATLG 

If this byte is omitted (set to zero), DA24DPS2 will be used. 


1 


DA24CTL 


Flag byte. These flags indicate to the DAIR service routine what 
operations are to be performed: 




XX 


Indicate the type of units desired for the space parameters, as follows: 




01 


Units are in average block length. 




10 


Units are in tracks (TRKS). 




11 


Units are in cylinders (CYLS). 




..1 

...1 .... 


Prefix userid to DSNAME. 
RLSE is desired. 




...1 .... 


The data set is to be permanently allocated; it is not be freed until 
specifically requested. 




1.. 

1. 


A DUMMY data set is desired. 
Attribute list name supplied. 







Reserved bit; set to zero. 


3 




Reserved bytes; set them to zero. 



Figure 10-12 (Part 2 of 3). DAIR Parameter Block - Entry Code X'24' 
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Number 
of Bytes 


Field 


Contents or Meaning 


1 

8 


DA24DSO 

1 

.1 

..1 

...1 .... 
.... 1... 

1.. 

1. 

1 

DA24ALN 


A flag field. These flags are set by the DAIR service routine; they 
describe the organization of the data set to the calling routine. 

Indexed sequential organization. 

Physical sequential organization. 

Direct organization. 

BTAM or QTAM line group. 

QTAM direct access message queue. 

QTAM problem program message queue. 

Partitioned organization. 

Unmovable. 

Attribute list name, or a DD name from which DCB attributes should 
be copied (as in a JCL DCB reference). If the name is less than eight 
characters, it should be padded to the right with blanks. 



Figure 10-12 (Part 3 of 3). DAIR Parameter Block - Entry Code X'24' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 8, 12, 16, 20, 52 

See "Return Codes from DAIR" for return code meanings. 

Code X'28' - Perform a List of DAIR Operations 

Build the DAIR parameter block shown in Figure 10-13 to request that DAIR 
perform a list of operations. This DAIR parameter block points to other DAPBs 
which request the operations to be performed. 

All valid DAIR functions are acceptable; however, code X'14' or another code 
X'28' are ignored. 

DAIR processes the requested operations in the order they are requested. 

DAIR processing stops with the first operation that fails. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 
2 
4 

4 


DA28CD 

DA28NOP 

DA28PFOP 

DA280PTR 


Entry code X'0028' 

Place in this field the number of operations to be performed. 

DAIR fills this field with the address of the DAIR parameter block for 
the first operation that failed. If all operations are successful, this field 
will contain zero upon return from the DAIR service routine. If this 
field contains an address, register fifteen contains a return code. 

Place in this field the address of the DAIR parameter block for the first 
operation you want performed. Repeat this field, filling it with the 
addresses of the DAPBs, for each of the operations to be performed. 



Figure 10-13. DAIR Parameter Block -- Entry Code X'28' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 8, 12, 16, 20, 24, 28, 32, 44, 52 

For return code meanings see the topic "Return Codes from DAIR." 
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Code X'2C - Mark Data Sets as Not in Use 



Build the DAIR parameter block shown in Figure 10-14 to request that DAIR 
mark data sets associated with a task control block as not in use. This allows 
data set entries to be reused. 

This is the code which the TMP should pass to DAIR prior to detaching a 
command processor. This code should also be issued by any command processor 
which attaches another command processor and detaches that command processor 
directly. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 


DA2CCD 


Entry code X'002C 


2 


DA2CFLG 


A flag field. Set the bits to indicate to the DAIR service routine which 
data sets you want marked 'not in use'. 

Hex 

Setting Meaning 

0000 Mark all data sets of the indicated TCB 'not in use'. 

0001 Mark the specified DDNAME 'not in use'. 

0002 Mark all data sets associated with lower tasks 'not in use'. 


4 


DA2CTCB 


Place in this field the address of the TCB for the task whose data sets 
are to be marked 'not in use'. DA2CFLG must be set to hex 0000. 


8 


DA2CDDN 


Place in this field the DDNAME to be marked 'not in use'. DA2CFLG 
must be set to hex 0001. 



Figure 10-14. DAIR Parameter Block ~ Entry Code X'2C 

After attempting the requested function, DAIR returns one of the following codes 
in register 15; 

0, 4, 52 

For return code meanings see "Return Codes from DAIR" later in this section. 



Code X'30' - Allocate a SYSOUT Data Set to the Message Class 



Build the DAIR parameter block shown in Figure 10-1.5 to request that DAIR 
allocate a SYSOUT data set to the message class. The exact action taken by 
DAIR is dependent upon the presence of the optional fields and the setting of bits 
in the control byte. To supply DCB information, provide the name of an 
attribute list that has been defined previously by a X'34' entry into DAIR, or the 
DDNAME of a currently allocated data set from which DCB attributes can be 
copied (as in a JCL DCB reference). 

To place a SYSOUT data set in a class other than the message class, use DAIR 
entry code X'30' and when the output has been written, specify the desired class 
either by using DAIR entry code X'18\ or execute the FREE command, after the 
program has completed processing. 

When setting disposition in a parameter list, only one bit should be on. 
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Number 
of Bytes 



Field 



Contents or Meaning 



DA30CD 
DA30FLG 



Byte 1 
1 



.000 0000 
Byte 2 
DA30DARC 



DA30PDSN 



DA30DDN 



DA30UNIT 



DA30SER 



DA30BLK 
DA30PQTY 

DA30SQTY 



Entry code X'0030' 

A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 

The data set is allocated but a secondary error occurred. Register 15 
contains an error code. 

Reserved bits. Set to zero. 

Reserved. Set to zero. 

This field contains the error code, if any, returned from the dynamic 
allocation routines. (See "Return Codes from Dynamic Allocation.") 

Reserved. Set this field to zero. 

Place in this field the address of the DSNAME buffer or zeros. The 
DSNAME buffer is a 46-byte field which must appear as follows: 

The first two bytes must contain 44 (X'2C); the next 44 bytes contain 
blanks. 

This field contains the DDNAME for the data set. If a specific 
DDNAME is not required, fill this field with eight blanks; DAIR will 
place in this field the DDNAME to which the data set is allocated. 

This is an eight-byte field containing an esoteric group name, a generic 
group name, or a specific device address (in EBCDIC). If the unit 
information is less than eight characters, it must be padded to the right 
with blanks. If no information is to be provided, the field must be 
blank. In this case, DAIR will obtain unit information from the 
protected step control block. If there is no unit information in the 
PSCB, then a default of all direct access devices is used. The specified 
unit information will be ignored if volume information is obtained from 
the catalog, unless the unit specification is a subset of that obtained 
from the catalog. In this case the specified unit information will 
override the returned information. 

Serial number desired. Only the first six bytes are significant. If the 
serial number is less than six bytes, it must be padded to the right with 
blanks. If no volume serial number is specified, the field must be 
blank. In this case, the following is done: If the data set is a new data 
set, the system determines the volume to be used for the data set based 
on the unit information. If the data set already exists, volume and unit 
information are obtained from the catalog. If the information is not 
found in the catalog, the allocation request is denied. 

Block size requested. This figure represents the average record length 
desired. 

Primary space quantity desired. The high-order byte must be set to 
zero; the low-order three bytes should contain the space quantity 
required. If the quantity is omitted, the entire field must be set to zero. 
In this case for new direct access data sets primary and secondary 
space, and type of space will be defaulted. 

Secondary space quantity desired. The high-order byte must be set to 
zero; the low-order three bytes should contain the secondary space 
quantity required. If the quantity is omitted, the entire field must be 
set to zero. 



Figure 10-15 (Part 1 of 2). DAIR Parameter Block - Entry Code X'30' 
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Number 
of Bytes 


Field 


Contents or Meaning 


8 


DA30PGNM 


Place in this field the member name of a special user program to handle 
SYSOUT operations. Fill this field with blanks if you do not provide a 
program name. 


4 


DA30FORM 


Form number. This form number indicates that the output should be 
printed or punched on a specific output form. It is a four character 
number. This field must be filled with blanks if this parameter is 
omitted. 


2 


DA30OCLS 


SYSOUT class. The data set will be allocated to the message class, 
regardless of the class you specify here. To place a SYSOUT data set 
in a class other than the message class, use DAIR entry code X'30' and 
when the output has been written, specify the desired class by using 
DAIR entry code X'18\ 


1 




Reserved. Set this field to zero. 


1 


DA30CTL 


Flag byte. These flags indicate to the DAIR service routine what 
operations are to be performed. 




XX 


Indicate the type of units desired for the space parameters, as follows: 




01 


Units are in average block length. 




10 


Units are in tracks (TRKS). 




11 

..1 


Units are in cylinders (CYLS). 
Prefix userid to DSNAME 




...1 .... 


RLSE is desired. 




.... 1... 
1.. 


The data set is to be permanently allocated; it is not to be freed until 
specifically requested. 

A DUMMY data set is desired. 




1. 


Attribute list name specified. 




0. 


Reserved bit; set to zero. 


8 


DA30ALN 


Attribute list name, or a ddname from which DCB attributes should be 
copied (as in a JCL DCB reference). If the name is less than eight 
characters, it should be padded to the right with blanks. 



Figure 10-15 (Part 2 of 2). DAIR Parameter Block -- Entry Code X'30' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0, 4, 12, 16, 20, 28, 52 

See "Return Codes from DAIR" later in this section for return code meanings. 

Code X'34' - Associate DCB Parameters with a Specified Name 

Build the DAIR parameter block shown in Figure 10-16 to request that DCB 
parameters to be used with subsequent allocations are associated with a specified 
name (attribute name). The following functions related to attribute names are 
available using code X'34': 

1 . Associate a set of DCB parameters to be used in subsequent allocations. 

2. Search on the attribute name. 

3. Delete the attribute name. 

Note: When you request that DAIR associate DCB parameters with a specified 
name, you must also build a DAIR attribute control block (DAIRACB). 
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Number 
of Bytes 


Field 


Contents or Meaning 


2 


DA34CD 


Entry code X'0034' 


2 


DA34FLG 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 




Byte 1 
DA34FIND 

1 



.000 0000 


An attribute list name was found. 
An attribute list name was not found. 
Reserved bits. Set to zero. 




Byte 2 


Reserved. Set to zero. 


2 


DA34DARC 


This field contains the code returned from the dynamic allocation 
routines. (See "Return Codes from Dynamic Allocation.") 


1 


DA34CTRL 


Flag byte. These flags indicate to DAIR what operations are to be 
performed. 




DA34SRCH 

1 


Search for the attribute list name specified in field DA34NAME. 




DA34CHN 
.1.. .... 


Build and chain an attribute list. 


1 


DA34UNCH 

..1 

...0 0000 


Delete an attribute list name. 
Reserved bits. Set to zero. 

Reserved. Set to zero. 


8 


DA34NAME 


This field contains the name for the list of attributes. 


4 


DA34ADDR 


This field contains the address of the DAIR attribute control block 
(DAIRACB). This field need only be specified if bit 1 of DA34CTRL 
is on. 



Figure 10-16. DAIR Parameter Block - Entry Code X'34' 

After attempting the requested function, DAIR returns one of the following codes 
in register 15: 

0,4,12,52 

See "Return Codes from DAIR" later in this section for return code meanings. 

DAIRACB - DAIR Attribute Control Block 

Build the DAIRACB shown in Figure 10-17 when you request that DAIR 
construct an attribute list. Place the address of the DAIRACB into the 
DA34ADDR field of the code X'34' DAIR parameter block shown in 
Figure 10-16. 
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Number 
of Bytes 


Field 


Contents or Meaning 


8 




Reserved. 


8 


DAIMASK 


First 6 bytes and eighth byte are reserved. 




DAILABEL 


Seventh-byte flags. These flags indicate the INOUT/OUTIN options of 
the OPEN macro. 




DAIINOUT 

1 


Use the INOUT option. 




DAIOUTIN 

.1 

..00 0000 


Use the OUTIN option. 

Reserved bits. Should be set to zero. 


3 




Reserved. Should be set to zero. 


3 


DAIEXPDT 


This field contains a data set expiration date specified in binary. 




DAIYEAR 


The first byte contains the expiration year. 




DAIDAY 


The next 2 bytes contain the expiration day, left justified. For example, 
the date 99352 is specified '630160'B. 


2 




Reserved. Should be set to zero. 


1 


DAIBUFNO 


This field contains the number of buffers required. 


1 


DAIBFTEK 


This field contains the buffer type and alignment. 




.1 

.11 

..1 

...1 .... 

1. 

1 

0... 00.. 


Simple buffering (S). 

Automatic record area construction (A). 

Record buffering (R). 

Exchange buffering (E). 

Doubleword boundary (D). 

Fullword boundary (F). 

Reserved bits. Should be set to zero. 


2 


DAIBUFL 


This field contains the buffer length. 


1 


DAIEROPT 


This field indicates the error options: 




1 

.1 

..1 

...0 0000 


Accept error record. 

Skip error record. 

Abnormal EOT. 

Reserved bits. Should be set to zero. 


1 


DAIEKYLE 


This field contains the key length. 


6 




Reserved. Should be set to zero. 


1 


DAIRECFM 


This field indicates the record format: 




1 

.1 

U 

..1 

...1 .... 
.... 1... 

1.. 

1. 




Fixed (F) 

Variable (V). 

Undefined (U). 

Track overflow (T). 

Blocked (B). 

Standard blocks (S). 

ASCII printer characters (A). 

Machine control characters (M). 

Reserved bit. Should be set to zero. 


1 


DAIOPTCD 


This field contains the error option codes: 




1 

..1 

.... 1... 

1. 

.0.0 .0.0 


Write validity check (W). 

Chained scheduling (C). 

ASCII translate (Q). 

User totaling (T). 

Reserved bits. Should be set to zero. 


2 


DAIBLKSI 


This field contains the maximum block size. 


2 


DAILRECL 


This field contains the logical record length. 


1 


DAINCP 


This field contains the maximum number of READ or WRITE channel 
programs before check. 


4 




Reserved. Should be set to zero. 



Figure 10-17. DAIR Attribute Control Block (DAIRACB) 

The fields that you do not use must be initialized to zero. 
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Return Codes from DAIR 



DAIR returns a code in general register 15 to the calling routine. In addition, 
further return code information may be found in the DAxxCTRC field if the 
return code is 8 or in the DAxxDARC field if the return code is 12. 

The DAIR return codes have the following meaning: 

Return 

Code Meaning 

(decimal) 

DAIR completed successfully. 

4 The parameter list passed to DAIR was invalid. 

8 An error occurred in a catalog management routine; the catalog management error code is 

stored in the CTRC field of the DAIR parameter block. 

12 An error occurred in dynamic allocation; the dynamic allocation error code is stored in the 

DARC field of the DAIR parameter block. 

16 No TIOT entries were available for use. 

20 The ddname requested is unavailable. 

24 The dsname requested is a member of a concatenated group. 

28 The ddname or dsname specified is not currently allocated, or the attribute list name 

specified was not found. 

32 The requested data set was previously permanently allocated, or was allocated with a 

disposition of new, and was not deleted. DISP = NEW cannot now be specified. 

36 An error occurred in a catalog information routine (IKJEHCIR). 

40 The return area you provided for qualifiers was exhausted and more index blocks exist. If 

you require more qualifiers, provide a larger return area. 

44 The previous allocation specified a disposition of DELETE for this non-permanently 

allocated data set. Request specified OLD, MOD, or SHR with no volume serial number. 

48 Reserved. 

52 Request denied by installation exit. 

The return codes from catalog management, which are found in the DAxxCTRC 
field if the register 15 return code is 8, are documented in SPL: Data 
Management. 
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Return Codes from Dynamic Allocation 



The codes returned in the DAxxDARC field of the DAIR parameter block, when 
a DAIR return code of 12 is returned, are the dynamic allocation error reason 
codes. (See SPL: System Macros and Facilities.) In addition to those return 
codes, which are converted from dynamic allocation codes back to the same codes 
which were used in previous releases, the following reason codes may also be 
returned: 



Return 
Code 

(hexadecimal) 

0304 

0308 

0314 

0318 

031C 

0320 

0324 

0328 

032C 

0330 

0334 

0338 

0348 

through 

034C 



Meaning 

The ddname was not specified by the calling routine. 

The ddname specified by the calling routine was not found. 

Restoring ddnames, as per this request, would have resulted in duplicate ddnames. 
Duplicate ddnames are not permitted. 

Invalid characters are present in the ddname provided by the caller. 

Invalid characters are present in the membername provided by the caller. 

Invalid characters are present in the dsname provided by the caller. 

Invalid characters are present in the SYSOUT program name provided by the caller. 

Invalid characters are present in the SYSOUT form number provided by the caller. 

An invalid SYSOUT class was specified by the caller. 

A membername was specified but the data set is not a partitioned data set. 

The supplied data set name exceeded 44 characters in length. 

The data set disposition specified by the caller is invalid. 

Reserved. 



DAIRFAIL Routine (IKJEFF18) 



The DAIRFAIL routine analyzes return codes from SVC99 or DAIR, and 
performs one of the following functions, as requested: 

• Issue an error message when appropriate. 

• Only return the error message to the caller. 

• Issue an error message, as well as return the message to the caller. 

This process of returning the message(s) to the caller is referred to as extracting 
the message. 

DAIRFAIL may be invoked in either 24- or 31 -bit addressing mode. When 
invoked in 31 -bit addressing mode, DAIRFAIL may be passed input that resides 
above 16 megabytes. 
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CP 



To invoke DAIRFAIL, link to IKJEFF18. When linking to IKJEFF18, provide 
the address of the following six-word parameter list in register 1 : 



Offset 






Dec Hex 


Field Name 


DSECT - 


DFDSECTD 






DFS99RBP 






or 







DFDAPLP 


4 4 




DFRCP 


8 8 




DFJEFF02 



DSECT - DFDSECTD 

DFS99RBP 
or 
12 C DFIDP 



16 10 



20 14 



DFCPPLP 



DFBUFP 



DSECT - DFDSECT2 

DFBUFS 
or 
DFBUFL1 



2 2 DFBUF01 

4 4 DFBUFT1 

256 100 DFBUFL2 

258 102 DFBUF02 

260 104 DFBUFT2 



Contents 



Address of the failing SVC99 request block or address of the failing 
DAIR parameter list. 

Address of a fullword containing either the SVC99 or DAIR return code. 

Address of a fullword containing either the entry point address of 
IKJEFF02 (message writer routine) or zeros, if that address is unknown. 
This field (DFJEFF02) must always contain an address. 



Address of a two-byte area containing: 

Byte 1 Switches 

BitO: - PUTLINE issued 



1 - WTP issued 



Bit 1: 1 

Bit 2: 1 



Caller wants message extracted only. 

Caller wants message extracted as well as issued using 
PUTLINE or write-to-programmer (WTO). 



Byte 2 Caller identification number 



X'01' - DAIR 
X'32' - SVC99 
X'33' - SVC99 invoked by the FREE command 

Address of the CPPL. This is needed only when IKJEFF18 is called 
with an SVC99 error and the user is not requesting a 
write-to-programmer message. 

Address of DFBUFS buffer if bit 2 (DFBUFSW) or bit 3 (DFBUFS2) of 
DFIDP is on. This is required when the message is to be extracted and 
returned to the caller. If the DFBUFSW is on, the message(s) will only 
be extracted. If DFBUFS2 is on, the message(s) will be issued as well as 
extracted and returned to the caller. It will be possible to extract the first 
level and one second level message. 



A 2 byte field that will contain the total length of the first level message, 
plus 4 bytes for length and offset fields. 

A 2 byte field containing the offset field. It will be set to zero when a 
message is extracted. 

A 251 byte buffer that will contain the text of the first level message 
extracted. If the message is greater than 251 bytes, the message will be 
truncated. 

A 2 byte field containing the total length of the first second level message 
plus four bytes. If there is no second level message, this field will contain 
HEX zeros. 

A 2 byte field containing the offset. It will be set to zero when a message 
is extracted. 

A 251 byte field that will contain the text of the first second level message 
extracted. If the message is greater than 251 bytes, the message will be 
truncated. 
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The IKJEFFDF macro may be used to map the fields in the parameter list. 
Specify the DFDSECT = YES option to obtain DSECT DFDSECTD instead of 
storage. Specify the DFSECT2 = YES option to obtain DSECT DFDSECT2 
instead of storage. 

DFDSECT2 defines a storage area supplied by the caller. DAIRFAIL will return 
the requested informational message(s) in the associated buffers. It is not 
necessary to initialize these buffers. On return from DAIRFAIL, the buffers will 
contain the extracted message(s). 

DAIRFAIL allows the user to specify that a write-to-programmer message should 
be issued rather than the default PUTLINE routine. This is especially useful for 
analyzing errors occurring in a batch invocation of SVC99. If the high-order bit 
of the caller identification area (pointed to by DFIDP) is on, a 
write-to-programmer message will be issued instead of a PUTLINE. When the 
write-to-programmer feature is used, the address of the CPPL (DFCPPLP) need 
not be specified. 

The return code from DAIRFAIL is contained in register 1 5 as follows: 

- Message issued successfully 

4 - Invalid caller identification number 

8 - Message writer detected an error while attempting to issue a message 

12 - Extracted message buffer parameter list error 



GNRLFAIL/VSAMFAIL Routine (IKJEFF19) 



The GNRLFAIL/VSAMFAIL routine analyzes VSAM macro instruction failures, 
subsystem request (SSREQ) failures, parse service routine or PUTLINE failures, 
and ABEND codes, and issues an appropriate error message. It will insert the 
meaning of return codes from the VSAM/job entry subsystem interface. Other 
VSAM codes are explained in the VSAM Programmer's Guide. 

GNRLFAIL/VSAMFAIL may be invoked in either 24- or 31 -bit addressing 
mode. When invoked in 31 -bit addressing mode, GNRLFAIL/VSAMFAIL may 
be passed input that resides above 16 megabytes. To invoke 
GNRLFAIL/VSAMFAIL, link to IKJEFF19. When linking to IKJEFF19, 
provide the address of a pointer to the following parameter list in register 1: 

Offset 
Dec Hex Field Name Contents 

GFCBPTR Pointer to VSAM ACB if GFOPEN or GFCLOSE callerid. 

Pointer to VSAM RPL for other VSAM macro failures. Pointer 
to SSOB if GFSSREQ caller id. 

4 4 GFRCODE Error return code from register 15 or ABEND code if 

GFCALLID is GFABEND. 

8 8 GF02PTR Zero, or address of TSO message issuer routine (IKJEFF02) if 

already loaded. 

12 C GFCALLID ID for caller's failing VSAM macro, or other failure. 
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Offset 




Dec Hex 


Field Name 




Hexadecimal 


GFCALLID = 


01 (GFCHECK) 




02 (GFCLOSE) 




03 (GFENDREQ) 




04 (GFERASE) 




05 (GFGET) 




06 (GFOPEN) 




07 (GFPOINT) 




08 (GFPUT) 




15 (GFPARSE) 




16 (GFPUTL) 




IF (GFABEND) 




20 (GFSSREQ) 


14 E 


GFBITS 




GFKEYN08 




GFSUBSYS 




GFWTPSW 


15 F 


GFRESV1 


16 10 


GFCPPLP 


20 14 


GFECBP 


24 18 


GFDSNLEN 


26 1A 


GFPGMNL 


28 IC 


GFDSNP 


32 20 


GFPGMNP 


36 24 


GFRESV2 


40 28 


GFRESV3 



Contents 

for VSAM CHECK macro error 

for VSAM CLOSE macro error 

for VSAM ENDREQ macro error 

for VSAM ERASE macro error 

for VSAM GET macro error 

for VSAM OPEN macro error 

for VSAM POINT macro error 

for VSAM PUT macro error 

for parse service routine error, other than a return code of 4 or 
20. 

for PUTLINE service routine error 

Issue ABEND message 

for Subsystem interface request (SSREQ) error 

Special processing switches 

1 Caller not in key or 8. 

.1 Caller used VS2 VSAM/job entry subsystem interface. 

..1 Issue error message as write-to-programmer instead of 

PUTLINE. 

Reserved. 

Pointer to TMP's CPPL control block (needed if PUTLINE 
issued, or to have command name inserted in the failure 

message). 

Pointer to ECB for PUTLINE (optional). 

Length of data set name. 

Length of program name. 

Pointer to data set name to insert in VSAMFAIL error messages 
(optional; default is ddname). 

Pointer to program name for insertion in all error messages 
(optional; default is ddname). 

Reserved. 

Reserved. 



The return code from GNRLFAIL is contained in register 15 as follows: 

- Message issued successfully 

80 - Invalid input parameter list (GFPARMS) for IKJEFF19. A message is also issued. 

Other - PUTLINE/PUTGET/IKJEFF02 message issuer error return code. 

The IKJEFFGF macro may be used to map the input parameter list. Specify the 
GFDSECT = YES option to obtain DSECT GFDSECTD instead of storage. 
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Chapter 11. Using BSAM or QSAM for Terminal I/O 



The basic sequential and queued sequential access methods provide terminal I/O 
support for programs operating under TSO. For a complete discussion of the use 
of BSAM and QSAM, see Data Management Services. 

The major benefit of using BSAM or QSAM to process terminal I/O under TSO 
is that programs using these access methods do not become TSO dependent or 
device dependent and may execute either under TSO or in the batch environment. 
Therefore, your existing programs that use BSAM or QSAM for I/O may be used 
under TSO without modification or recompilation. 

This section describes: 

• The BSAM/QSAM macro instructions 

• SAM terminal routines 

• Record formats, buffering techniques, and processing modes 

• Specifying the terminal line size 

• End of file (EOF) for input processing 

• Modifying DD statements for batch or TSO processing 



BSAM/QSAM Macro Instructions 



Some of the BSAM and QSAM access method routines have been modified to 
provide special services under TSO; others provide the same function that is 
provided in a batch environment. Those BSAM/QSAM macro instructions that 
are not relevant to terminal I/O act as no-ops. All of the BSAM/QSAM macro 
instructions, when executed in the batch environment, provide the non-terminal 
functions as explained in Data Management Macro Instructions. The 
BSAM/QSAM macro instructions must be issued in 24-bit addressing mode. 
Figure 11-1 shows the functions performed by the BSAM and QSAM macro 
instructions when used for terminal I/O. Following the table are more detailed 
explanations of the GET, PUT, PUTX, READ, WRITE, and CHECK macro 
instructions. 
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SAM Macro 








Instruction 


BSAM 


QSAM 


Terminal Interpretation 


BSP 


X 


X 


NOP 


BUILD 


X 


X 


As in batch processing, the BUILD macro instruction causes a 
buffer pool to be constructed in a user-provided storage area. 


CHECK 


X 




Takes an EODAD exit after a READ EOF. NOP after a 
WRITE. 


CLOSE 


X 


X 


The CLOSE macro instruction frees the control blocks built to 
handle I/O and deletes the loaded SAM terminal routines. 


CNTRL 


X 


X 


NOP 


REOV 


X 


X 


NOP 


FREEBUF 


X 




As in batch processing, the FREEBUF macro instruction 
causes the control program to return a buffer to the buffer 
pool assigned to the specified data control block. 


FREEPOOL 


X 


X 


As in batch processing, the FREEPOOL macro instruction 
causes an area of virtual storage, previously assigned as a 
buffer pool for a specified data control block, to be released. 


GET 




X 


The GET macro instruction obtains data from the terminal via 
the TGET macro instruction. 


GETBUF 


X 




As in batch processing, the GETBUF macro instruction causes 
the control program to obtain a buffer from the buffer pool 
assigned to the specified data control block, and to return the 
address of the buffer in a designated register. 


GETPOOL 


X 


X 


As in batch processing, the GETPOOL macro instruction 
causes a buffer pool to be constructed in a storage area 
provided by the control program. 


NOTE 


X 




NOP 


OPEN 


X 


X 


The OPEN macro instruction loads the proper SAM terminal 
I/O routines and constructs the necessary control blocks. 


POINT 


X 




NOP 


PRTOV 


X 


X 


NOP 


PUT 




X 


The PUT macro instruction routes data to the terminal via the 
TPUT macro instruction. 


PUTX 




X 


The PUTX macro instruction routes data to the terminal via 
the TPUT macro instruction. 


READ 


X 




The READ macro instruction obtains data from the terminal 
via the TGET macro instruction. 


RELSE 




X 


NOP 


SETPRT 


X 


X 


NOP 


TRUNC 




X 


NOP 


WRITE 


X 




The WRITE macro instruction routes data to the terminal via 
the TPUT macro instruction. 



Figure 11-1. BSAM/QSAM Macro Functions Under TSO 



SAM Terminal Routines 



The GET, PUT, PUTX, READ, WRITE, and CHECK macro instructions 
perform differently in terminal I/O than they do in the batch environment. 
Descriptions of these differences are presented here, but for a detailed explanation 
of how to use the macro instructions, see Data Management Macro Instructions. 
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GET 



PUT and PUTX 



READ 



The GET macro instruction causes a record to be retrieved from the terminal and 
placed in either the first buffer of the buffer pool control block (locate mode) or 
in a user specified area (substitute or move mode). In either case, the address of 
the record is returned in register 1 . 

The record is moved via a TGET macro instruction which does not return control 
until the transfer of data completes. 

The input to the GET macro instruction consists of the DCB address and the 
user's area address (omitted for locate mode). The output is edited (that is, 
specially-indicated characters are deleted from the message). Lowercase 
characters are folded to uppercase characters. 

When the terminal user types /*, end-of-file is indicated and control is passed to 
the problem program's EODAD routine. If no EODAD routine is specified, the 
job will ABEND with a system code of 337. 



Both the PUT and the PUTX macro instructions cause a record to be written to a 
terminal. This transfer of data is accomplished with the TPUT macro instruction 
which does not return control until the transfer is completed. 

In locate mode, the first use of PUT or PUTX causes an address pointing to a 
buffer to be returned in register 1. The first record is placed in this buffer by the 
problem program and is written out when the next PUT or PUTX for the same 
data control block (DCB) is issued. Succeeding records are written in the same 
manner. The last record is written at CLOSE time. 

In move or substitute mode, the PUT or PUTX macro instruction moves a record 
from the user-specified work area to the terminal. You must supply the work 
area address to the PUT macro instruction. 

The input to the PUT and PUTX macro instruction consists of the DCB address 
and the user's area address (omitted for locate mode). 



The READ macro instruction causes a block of data to be retrieved from the 
terminal and placed in a user-designated area in storage. This transfer of data is 
done via a TGET macro instruction which does not return control before the 
transfer is completed. The data is folded to uppercase. 

The input to the READ macro instruction consists of the string of parameters 
explained in Data Management Macro Instructions. 
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WRITE 



CHECK 



The WRITE macro instruction causes a block of data to be written from the 
user-specified area to the terminal. This transfer of data is done via a TPUT 
macro instruction which does not return control until the transfer is completed. 

The input to the WRITE macro instruction consists of the string of parameters 
explained in Data Management Macro Instructions. 



The CHECK macro instruction used after a WRITE macro instruction results in 
a NOP. When it is used after a READ macro instruction, it performs as a NOP 
unless an end of file (EOF) condition is encountered. The end of file signal from 
the terminal is-/*. When end of file is encountered, CHECK takes the EODAD 
exit specified in the data control block. If no EODAD exit is specified, CHECK 
will cause the job to ABEND with a system code of 337. 

The input to the CHECK macro instruction is the address of the problem 
program's data event control block (DECB). 



Record Formats, Buffering Techniques, and Processing Modes 



All record formats — fixed (F), variable (V), and undefined (U) -- are supported 
under TSO. Before passing the data to the problem program, TSO automatically 
generates the first four bytes of control information for V format records coming 
in from the terminal. When you send V format records to the terminal, TSO 
automatically removes the control information before writing the line. 

Control characters (ASCII or machine) are not supported under TSO. On output, 
they are removed before the data is sent to the terminal. On input, they are 
ignored. 

Both simple and exchange buffering techniques are supported, as are all four 
processing modes for the queued access method. 



Specifying Terminal Line Size 



If the LRECL and BLKSIZE fields are not specified in the DCB, the terminal 
line size default (or the line size the terminal user has specified via the 
TERMINAL command) is merged into the data control block fields as if it came 
from the label of the data set. 

For BSAM, BLKSIZE is used by TSO to determine the length of the text line it is 
to process. For both BSAM and QSAM, if the text entered from the terminal is 
shorter than the value specified for LRECL, and if F format is used, blanks are 
supplied On the right. For either access technique, if the text entered is longer 
than BLKSIZE or LRECL, the next GET or READ retrieves the remainder of 
the message. If the record generated by the problem program is longer than the 
specified line size, multiple lines are displayed at the terminal. 
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End-of-File (EOF) for Input Processing 



The sequential access method GET and CHECK terminal routines recognize /* 
from the terminal as an end-of-file (EOF). The EODAD exit in the data control 
block is taken for the EOF condition. If no EODAD exit has been specified, and 
an EOF has been signaled from the terminal, the job ABENDs with a system 
code of 337. 



Modifying DD Statements for Batch or TSO Processing 



TERM = TS, when added to a DD statement defining an input or an output data 
set, is ignored in the batch processing environment, but under TSO indicates to 
the system that the unit to which I/O is being addressed is a time sharing 
terminal. Thus a user who wants his job to run in either the foreground or the 
background could provide a DD statement as follows: 



//DD1 DD TERM=TS,SYSOUT=A 



In this example the output device is defined as a terminal under TSO processing, 
and as the SYSOUT device during batch processing. For a complete description 
of the TERM = TS parameter, see JCL. 
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Chapter 12. Using the TSO I/O Service Routines for Terminal I/O 



The TSO I/O service routines process terminal I/O requests initiated by the 
terminal monitor program (TMP), command processors (CPs), and other service 
routines. If you write your own command processors, or replace the 
IBM-supplied terminal monitor program with one of your own design, you should 
use the I/O service routines to process terminal I/O. 

The I/O service routines - STACK, GETLINE, PUTLINE, and PUTGET - 

offer the following features: 

1. They provide an interface between an I/O request and the TGET and TPUT 
supervisor calls. 

2. They provide a method of selecting sources of input other than the terminal. 
Requests for input can be directed to an in-storage list or data set as well as 
to the terminal. 

3. They provide a message formatting facility with which you can insert text 
segments into a basic message format, and display or inhibit the displaying of 
message identifiers. 

4. They process requests for more information (question-mark processing), and 
they analyze processing conditions to determine if I/O requests should be 
disregarded or honored. 

You pass control to the I/O service routines and indicate the functions you want 
performed by coding the operands you require in the list and the execute forms of 
the I/O service routine macro instructions. Each of the I/O service routine macro 
instructions (STACK, GETLINE, PUTLINE, and PUTGET) has a list and an 
execute form. 

The list form of each service routine macro instruction initializes the parameter 
blocks according to the operands you code into the macro instruction. 

The execute form is used to modify the parameter blocks and to provide linkage 
to the service routines, and can be used to set up the input/output parameter list. 
The input/output parameter list contains addresses required by the I/O service 
routines. 

Note: See the section "Processing Terminal Requests -- The TSO Service 
Routines" for information on the CALLTSSR macro interface to TSO service 
routines and a list of the t)SECTs provided for TSO control blocks. 
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The Input/Output Parameter List 



The I/O service routines use two of the pointers contained in the command 
processor parameter list: the pointer to the user profile table and the pointer to 
the environment control table. These addresses are passed to the service routines 
in another parameter list, the input/output parameter list (IOPL). The IOPL may 
reside above or below 16 megabytes. If the IOPL resides above 16 megabytes, 
then the caller must run in 31 -bit addressing mode. Before executing any of the 
TSO I/O macro instructions (GETLINE, PUTLINE, PUTGET, or STACK), you 
must provide an IOPL and pass its address to the I/O service routine. There are 
two ways you can construct an IOPL: 

1 . You can build and initialize the IOPL within your code and place a pointer to 
it in the execute form of the I/O macro instruction. 

2. You can provide space for an IOPL (4 fullwords), pass a pointer to it, 
together with the addresses required to fill it, to the execute form of the I/O 
macro instruction, and let the I/O macro instruction build the IOPL for you. 

The input/output parameter list, as defined by the IKJIOPL DSECT, is a 
four-word parameter list. Figure 12-1 describes the contents of the IOPL. 



Number 
of Bytes 



Field 



Contents or Meaning 



IOPLUPT 
IOPLECT 
IOPLECB 



IOPLIOPB 



The address of the user profile table from the CPPLUPT field of the 
command processor parameter list. 

The address of the environment control table from the CPPLECT field of 
theCPPL. 

The address of the command processor's event control block (ECB). The 
ECB is one word of storage, declared and initialized to zero by the 
command processor. Command processors with attention exits can post 
this ECB after an attention interruption to cause active service routines 
to exit. 

The address of the parameter block created by the list form of the I/O 
macro instruction. There are four types of parameter blocks, one for 
each of the I/O service routines: 



STACK parameter block (STPB) 
GETLINE parameter block (GTPB) 
PUTLINE parameter block (PTPB) 
PUTGET parameter block (PGPB) 



Figure 12-1. The Input/Output Parameter List 

The parameter block pointed to by the fourth word (IOPLIOPB) of the I/O 
parameter list is built and modified by the I/O service routine macros themselves. 
It is created and initialized by the list form of the I/O macro instruction, and 
modified by the execute form. Thus you can use the same parameter block to 
perform different functions. All you need to do is code different parameters in 
the execute forms of the macro instructions; these parameters provide those 
options not specified in the list form, and override those which were specified. 
Each of these parameter blocks - the STACK, GETLINE, PUTLINE, and 
PUTGET parameter blocks - is described in the separate sections on each of the 
I/O macro instructions. 
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Figure 12-2, an extension of Figure 10-17, summarizes the control block 
interfaces established between the terminal monitor program and an I/O service 
routine. 







ATTACH 










Terminal 
Monitor 
Program 


Command 
Processor 






Register 1 1 






















CPPL 



























Figure 12-2. Control Block Interface Between the TMP and I/O Service Routine 



Passing Control to the I/O Service Routines 



The I/O service routines may be invoked in either 24-bit or 31 -bit addressing 
mode. These routines execute in 31 -bit addressing mode. Input may reside above 
or below 16 megabytes, except for the list storage descriptor (LSD). The LSD 
must reside below 16 megabytes. 

Service routines treat input addresses according to the addressing mode in which 
they are invoked. However, if you use the GETLINE macro, the addressing 
mode of the STACK macro will be used rather than your program's addressing 
mode. Address values will be treated as 24-bit or 31 -bit addressing mode 
depending on the addressing mode of the original issuer of the STACK macro for 
that element. 



Chapter 12. Using the TSO I/O Service Routines for Terminal I/O 12-3 



Pass control to an I/O service routine using the corresponding I/O macro 
instruction: 



Service Routine 


Macro Instruction 


STACK 


STACK 


GETLINE 


GETLINE 


PUTLINE 


PUTLINE 


PUTGET 


PUTGET 



You can use the DELETE macro instruction to release the storage area occupied 
by the load module when you have finished with your terminal I/O. Service of 
the TSO terminal I/O service routines are contained in the IKJPTGT load 
module. 



The I/O Service Routine Macro Instructions 



The I/O service routines -- STACK, GETLINE, PUTLINE, and PUTGET -- 

each perform a specific I/O function: 

• STACK determines the source of input. 

• GETLINE obtains a line of input. 

• PUTLINE puts a line of output to the terminal. 

• PUTGET puts a line to the terminal and gets a line in response. 

In order to perform these functions, the I/O macro instructions use the control 
blocks explained in the section "Processing Terminal Requests - The TSO Service 
Routines" and other, more individualized control blocks, the parameter blocks. 
Each of the I/O macro instructions has a list and an execute form. The list form 
sets up the parameter block required by that I/O service routine; the execute form 
can be used to set up the input output parameter list, and to modify the 
parameter block created by the list form of the macro instruction. 

The STACK, GETLINE, PUTLINE, and PUTGET macros may be issued in 
either 24- or 3 1 -bit addressing mode. The corresponding I/O service routines 
execute in 31 -bit addressing mode and return control in the same addressing mode 
in which they are invoked. Input may reside above or below 16 megabytes, 
except for the list source descriptor (LSD). The LSD must reside below 16 
megabytes. 

The parameter block required by each of the I/O service routines is different, and 
each one may be referenced through a DSECT. The parameter blocks and the 
D SECTS used to reference them are: 

• The STACK parameter block referenced by IKJSTPB 

• The GETLINE parameter block referenced by IKJGTPB 

• The PUTLINE parameter block referenced by IKJPTPB 

• The PUTGET parameter block referenced by IKJPGPB 

Each of these blocks is explained in the section describing the I/O macro 
instruction that builds it. 
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STACK - Changing the Source of Input 



Use the STACK macro instruction to establish and to change the source of input. 
The currently active input source is described by the top element of the input 
stack, an internal pushdown list maintained by the I/O service routines. The first 
element of the input stack is initialized by the terminal monitor program (TMP), 
and cannot thereafter be changed or deleted. The IBM-supplied TMP initializes 
this first element to indicate the terminal as the current input source. The 
STACK service routine adds an element to the input stack or deletes one or more 
elements from it, and thereby changes the source of input for the other I/O service 
routines. 

The STACK service routine saves the addressing mode of the program that 
invoked it. Address values will be treated as 24-bit or 31 -bit addressing mode 
depending on the addressing mode of the original issuer of STACK for that 
element. 

This topic describes: 

• The list and execute forms of the STACK macro instruction 

• The sources of input 

• The STACK parameter block 

• The list source descriptor 

• Return codes from STACK 



Coding examples are included where needed. 
The STACK Macro Instruction - List Form 



The list form of the STACK macro instruction builds and initializes a STACK 
parameter block (STPB), according to the operands you specify in the macro. 
The STACK parameter block indicates to the STACK service routine which 
functions you want performed. Figure 12-3 shows the list form of the STACK 
macro instruction; each of the operands is explained following the figure. 
Appendix A describes the notation used to define macro instructions. 



[symbol] 



STACK 



DELETE= 



TOP 

PROC 

ALL 



PROCN, PROMPT 



STORAGE=( element address, 



PROCL , PROMPT ) 
SOURCE 



DATASET= ( INDD=addl , PROMPT , LIST 
iMEMBER=addr3 
OUTDD=addr 2 , CNTL , SEQ 
CLOSE 



,MF=L 



Figure 12-3. The List Form of the STACK Macro Instruction 



DELETE = 

Delete an element or elements from the input stack. The element to be 
deleted must be further defined as TOP, PROC, or ALL. 
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TOP 

The topmost element (the element most recently added to the input stack) is 
to be deleted. 

PROC 

The current procedure element is to be deleted from the input stack. If the 
top element is not a PROC element, all elements down to and including the 
first PROC element encountered are to be deleted. 

ALL 

All elements are to be deleted from the input stack except the bottom 
element (the first element). 

STORAGE = element address 

Add an in-storage element to the input stack. The element address is the 
address of the list source descriptor (LSD). The LSD is a control block, 
pointed to by the STACK parameter block, which describes the in-storage 
list. The LSD must reside below 16 megabytes. The in-storage element 
must be further defined as a SOURCE, PROCN, or PROCL list. SOURCE 
is the default. 

PROMPT 

Specifies prompting by commands within a command procedure. PROMPT 
is used with the keywords PROCN and PROCL, which specify that the 
element to be added to the input stack is a command procedure. 

PROCN 

The element to be added to the input stack is a command procedure and the 
NOLIST option has been specified. 

PROCL 

The element to be added to the input stack is a command procedure and the 
LIST option has been specified. Each line read from the command 
procedure is written to the terminal. 

SOURCE 

The element to be added to the input stack is an in-storage source data set. 

MF = L 

Indicates that this is the list form of the macro instruction. 

DATASET 

Supports the use of ACCOUNT in the background by expanding the 
facilities of dataset I/O for TSO commands to include reading from a 
SYSIN data set and writing to a SYSOUT dataset. To use the dataset 
function, the input and output files passed to the STACK service routine 
must be preallocated, either by a previously issued ALLOCATE command, 
a command processor going to dynamic allocation, a DD statement 
specified in the logon procedure, or, in the background, a user-supplied DD 
statement. 



Specifies that STACK use the bottom element in the input stack for I/O 
operations. This operand is the functional equivalent of TERM = *. 
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INDD = addrl 

Specifies the input file name. 

PROMPT 

Allows prompting if prompting is also allowed on the bottom element of the 
input stack. 

LIST 

Lists the input from the input stream. 

MEMBER = addr3 

Specifies an 8-character member name for a partitioned data set which was 
specified as the input file with the INDD operand. 

OUTDD = addr2 

Specifies the output file name. 

CNTL 

The output line has its own control character. 

CLOSE 

Closes the data control blocks (DCBs) of the input stack. 

SEQ 

Tells dataset I/O not to remove sequence numbers. 

Note: In the list form of the macro instruction, only 



STACK MF=L 



is required. When only STACK MF = L is specified, the STPB is zeroed. The 
other operands and their sublists are optional because they may be supplied by 
the execute form of the macro instruction. 

The operands you specify in the list form of the STACK macro instruction set up 
control information used by the STACK service routine. The DATASET, 
STORAGE, and DELETE operands set bits in the STACK parameter block. 
These bit settings indicate to the STACK service routine which options you wish 
performed. 



The STACK Macro Instruction - Execute Form 



Use the execute form of the STACK macro instruction to perform the following 
three functions: 

1. To set up the input output parameter list (IOPL). 

2. To initialize those fields of the STACK parameter block not initialized by the 
list form of the macro instruction, or to modify those fields already initialized. 

3. To pass control to the STACK service routine which modifies the input stack. 
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Figure 12-4 shows the execute form of the STACK macro instruction; each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



[symbol] 


STACK 


[PARM=parm addr . ] [ ,UPT=upt addr.] 
[,ECT=ect addr. ] [ ,ECB=ecb addr.] 








(TOP 
DELETE= PROC 
(ALL 












( PROCN , PROMPT j 
STORAGE= ( element addr . , j PROCL , PROMPT j ) 

( SOURCE ) 










DATASET= 


INDD=addl , PROMPT , LIST I 
MEMBER=addr3 j 
OUTDD=addr2,CNTL,SEQ I 
CLOSE ) 










,ENTRY=)entry addr.\ 
t (15) }_ 


,MF= (Enlist addr.\) 

i (1 > /. 



Figure 12-4. The Execute Form of the STACK Macro Instruction 



Note: TERM = * will be allowed by STACK to provide compatibility with 
existing modules when they are recompiled. 

PARM = parm addr 

Specifies the address of the 2-word STACK parameter block (STPB). It 
may be the address of the list form of the STACK macro instruction. The 
address is any address valid in an RX instruction, or the number of one of 
the general registers 2-12 enclosed in parentheses. This address will be 
placed in the input/output parameter list (IOPL). The STPB should be 
created using the list form of STACK. The STPB must be zeroed if no list 
options are specified. The STPB and IOPL (STPL) may be modified by 
STACK, so they should be in reentrant storage if used in a reentrant 
program. 

UPT = uptaddr 

Specifies the address of the user profile table (UPT). This address may be 
obtained from the command processor parameter list pointed to by register 
one when the command processor is attached by the terminal monitor 
program. The address may be any address valid in an RX instruction or the 
number of one of the general registers 2-12 enclosed in parentheses. This 
address will be placed in the input/output parameter list (IOPL). 

ECT = ectaddr 

Specifies the address of the environment control table (ECT). This address 
may be obtained from the CPPL pointed to by register 1 when the 
command processor is attached by the terminal monitor program. The 
address may be any address valid in an RX instruction or the number of 
one of the general registers 2-12 enclosed in parentheses. This address will 
be placed in the IOPL. 
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ECB = ecbaddr 

Specifies the address of an event control block (ECB). This address will be 
placed into the IOPL. You must provide a one-word event control block 
and pass its address to the STACK service routine by placing it into the 
IOPL. The address may be any address valid in an RX instruction or the 
number of one of the general registers 2-12 enclosed in parentheses. 

TERM = * 

Add a terminal element to the input stack. 

DELETE 

Delete one or more elements from the input stack. Specify which element, 
either TOP, PROC, or ALL. 

TOP 

The topmost element (the element most recently added to the input stack) is 
to be deleted. 

PROC 

The current procedure element is to be deleted from the input stack. If the 
top element is not a procedure element, all elements down to and including 
the first procedure element encountered are to be deleted. 

ALL 

All elements are to be deleted from the input stack except the bottom 
element (the first element). 

STORAGE = element address 

Add an in-storage element to the input stack. The element address is the 
address of the list source descriptor (LSD). The LSD is a control block, 
pointed to by the stack parameter block, which describes the in-storage list. 
The in-storage list must be further defined as a SOURCE, PROCN, or 
PROCL list. SOURCE is the default. 

SOURCE 

The element to be added to the input stack is an in-storage source data set. 

PROCN 

The element to be added to the input stack is a command procedure and the 
NOLIST option has been specified. 

PROCL 

The element to be added to the input stack is a command procedure and the 
LIST option has been specified. Each line read from the command 
procedure is written to the terminal. 

PROMPT 

Specifies prompting by commands within a command procedure. PROMPT 
is used with the keywords PROCN and PROCL, which specify that the 
element to be added to the input stack is a command procedure. 
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DATASET 

Supports the use of ACCOUNT in the background by expanding the 
facilities of dataset I/O for TSO commands to include reading from a 
SYSIN dataset and writing to a SYSOUT dataset. To use the dataset 
function, the input and output files passed to the STACK service routine 
must be preallocated, either by a previously issued ALLOCATE command, 
a command processor going to dynamic allocation, a DD statement 
specified in the logon procedure, or, in the background, a user-supplied DD 
statement. 



Specifies that STACK use the bottom element on the input stack for I/O 
operations. 

INDD = addrl 

Specifies the input file name. 

PROMPT 

Allows prompting if prompting is also allowed on the bottom element of the 
input stack. 

LIST 

Lists the input from the input stream. 

MEMBER = addr3 

Specifies the 8-character member name for the input file. 

OUTDD = addr2 

Specifies the output file name. 

CNTL 

The output line has its own control character. 

SEQ 

Tells dataset I/O not to remove sequence numbers. 

CLOSE 

Closes the data control blocks (DCBs) of the bottom element of the input 
stack. 

ENTRY = entry address or (15) 

Specifies the entry point of the STACK service routine. The address may be 
any address valid in an RX instruction or (15) if the entry point address has 
been loaded into general register 15. If ENTRY is omitted, a LINK macro 
instruction will be generated to invoke the STACK service routine. 

MF = E 

Indicates that this is the execute form of the macro instruction. 

listaddr 

(1) 

The address of the four-word input/output parameter list (IOPL). This may 
be a completed IOPL that you have built, or it may be 4 words of declared 
storage that will be filled from the PARM, UPT, ECT, and ECB operands 
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of this execute form of the STACK macro instruction. The address is any 
address valid in an RX instruction or (1) if the parameter list address has 
been loaded into general register 1. 

Note: In the execute form of the STACK macro instruction only the following 
operands are required: 



STACK 



MF=(E, 



(list address)) 

i (i) ; 



Sources of Input 



The PARM, UPT, ECT, and ECB operands are not required if you have built an 
IOPL in your own code. 

The other operands and their sublists are optional because they may be supplied 
by the list form of the macro instruction. 

The ENTRY operand need not be coded in the macro instruction. If it is not, a 
LINK macro instruction will be generated to invoke the I/O service routine. 

The operands you specify in the execute form of the STACK macro instruction 
are used to set up control information used by the STACK service routine. You 
can use the PARM, UPT, ECT, and ECB operands of the STACK macro 
instruction to complete, build, or alter an IOPL. The DATASET, STORAGE, 
and DELETE operands set bits in the STACK parameter block. These bit 
settings indicate to the STACK service routine which options you want. 



The input sources provided are defined as follows: 

1 . Terminal 

If the terminal is specified in the STACK macro instruction as the input 
source, all input and output requests through GETLINE, PUTLINE, and 
PUTGET are read from the terminal and written to the terminal. The user at 
the terminal controls TSO by entering commands; the system processes these 
commands as they are entered and returns to the user for another command. 

When an online job is running, the first element in the input stack is a 
terminal element. 

2. In-Storage List 

An in-storage list can be either a list of commands or a source data set. It 
may contain variable-length records (with a length header) or fixed-length 
records (no header and all records the same length). In either case, no one 
record on an in-storage list may exceed 256 characters. 

When a job is running in the background, the first element in the input stack 
is a data set element. 
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An in-storage list and its processing are specified by setting the STORAGE 
operand type to PROCN, PROCL, or SOURCE. 

• PROCN or PROCL - Indicates that the in-storage list is a command 
procedure, a list of commands to be executed in the order specified. If you 
specify PROCN, requests through GETLINE are read from the in-storage 
list, but PROMPT requests from the executing command processor are 
suppressed. MODE messages, those messages normally sent to the terminal 
requesting entry of a command or a sub-command, are not sent but a 
command is obtained from the in-storage list. If the PROCL option is 
specified, the command is displayed at the terminal as it is read from the list. 

• SOURCE - Indicates that the in-storage list is a source data set. Requests 
through GETLINE are read from the in-storage list, but PROMPT requests 
from the executing command processor are honored if prompting is allowed, 
and a line is requested from the terminal. MODE messages are handled the 
same way as with PROCN or PROCL. No LIST facility is provided with 
SOURCE records. 



Building the STACK Parameter Block 



When the list form of the STACK macro instruction expands, it builds a five 
word STACK parameter block (STPB). The list form of the macro instruction 
initializes this STPB according to the operands you have coded. This initialized 
block, which you may later modify with the execute form of the macro 
instruction, indicates to the I/O service routine the functions you want performed. 

By using the list form of the macro instruction to initialize the block, and the 
execute form to modify it, you can use the same STPB to perform different 
STACK functions. Keep in mind, however, that if you specify an operand in the 
execute form of the macro instruction, and that operand has a sublist as a value, 
the default values of the sublist will be coded into the STPB for any of the sublist 
values not coded. If you do not want the default values, you must code each of 
the values you require, each time you change any one of them. 

For example, if you coded the list form of the STACK macro instruction as 
follows: 



STACK 



STORAGE=( element address , PROCN) ,MF=L 



and then overrode it with the execute form of the macro instruction as follows: 



STACK 



STORAGE=(new element address), 
MF=(E,list address) 



The element code in the STACK parameter block would default to SOURCE, the 
default value. If the new in-storage list was another PROCN list, you would have 
to respecify PROCN in the execute form of the macro instruction. 

The STACK parameter block is defined by the IKJSTPB DSECT. Figure 12-5 
describes the contents of the STPB. 
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Number 
of Bytes 


Field 


Contents or Meaning 


1 


none 


Operation code: A flag byte which describes the operation to be 
performed. 




1 


One element is to be added to the top of the input stack. 




.1 


The top element is to be deleted from the input stack. 




..1 


The current procedure is to be deleted from the input stack. If the top 
element is not a PROC element, all elements down to and including the 
first PROC element encountered are deleted, except the bottom 
element. 




...1 .... 


All elements except the bottom one (the first element) are to be deleted. 




xxxx 


Reserved bits. 


1 


none 


Element code: A flag byte describing the element to be added to the 
input stack. 




1 

.1 

..1 

...1 .... 
.... 1... 

1.. 

0. 

1. 

1 


A terminal element. 

An in-storage element. 

Input DD name present. 

Output DD name present. 

The in-storage element is an EXEC command element. 

Prompting is allowed from the PROC element. 

The in-storage element is a source element. 

The in-storage element is a procedure element. 

The list option (PROCL) has been specified. 


1 




Reserved. 


1 


none 


DATASET operation. 




xxxx X... 

1.. 

1. 

1 


Reserved. 

Do not remove sequence numbers. 

User-specified CNTL. 

Close option. 


4 


STPBALSD 


The address of the list source descriptor (LSD). An LSD describes an 
in-storage list. If the input source is the terminal, or if DELETE has 
been specified, this field will contain zeros. 


4 


STPBINDD 


Pointer to input DD name. 


4 


STPBODDN 


Pointer to output DD name. 


4 


STPBMBRN 


Pointer to membername. 



Figure 12-5. The STACK Parameter Block 

If the DATASET or DELETE operands have been coded in the STACK macro 
instruction, the second word of the stack parameter block will contain zeroes and 
the control block structure will end with the STPB. Figure 12-6 describes this 
condition. 
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Terminal 
Monitor 
Program 



ATTACH 



Command 
Processor 



LINK 



STACK 
Service 
Routine 



Reg. 1 



Reg. 1 



CPPL 



IOPL 



STPB 



00000000 



Figure 12-6. STACK Control Blocks: No In-Storage List 



To add an in-storage list element to the input stack, you must describe the 
in-storage list and pass a pointer to it to the STACK I/O service routine. You do 
this by building a list source descriptor (LSD). The LSD must reside below 16 
megabytes. 

Figure 12-7 is an example of the code required to add the terminal to the input 
stack as the current input source. In this example, the execute form of the 
STACK macro instruction is used to build the input/output parameter list for 
you. The list form of the STACK macro instruction expands into a STACK 
parameter block, and its address is passed to the execute form of the macro 
instruction as the PARM operand address. 
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Figure 12-7. Coding Example - STACK Specifying the Terminal as the Input Source 



This sequence of code does not make use of the IKJCPPL DSECT to access the 
command processor parameter list, nor does it provide reenterable code. 



Building the List Source Descriptor (LSD) 



A list source descriptor (LSD) is a four-word control block that describes the 
in-storage list pointed to by the new element you are adding to the input stack. 
Note that the LSD must reside below 16 megabytes. If you are designating the 
terminal as the input source, no LSD is necessary and the second word of the 
STPB will be zero. If you specify STORAGE as the input source in the STACK 
macro instruction, your code must build an LSD, and place a pointer to it as a 
sublist of the STORAGE operand. The LSD must begin on a doubleword 
boundary, and must be created in the shared subpool designated by the terminal 
monitor program; the IBM-supplied TMP shares subpool 78 with the command 
processors. The LSD is defined by the IKJLSD DSECT. Figure 12-8 describes 
the contents of the LSD. 



Chapter 12. Using the TSO I/O Service Routines for Terminal I/O 12-15 



Number 
of Bytes 


Field 


Contents or Meaning 


4 

2 

2 
4 

4 


LSDADATA 
LSDRCLEN 

LSDTOTLN 

LSDANEXT 

LSDRSVRD 


The address of the in-storage list. 

The record length if the in-storage list contains fixed-length records. 
Zero if the record lengths are variable. 

The total length of the in-storage list; the sum of the lengths of all 
records in the list. 

Pointer to the next record to be processed. Initialize this field to the 
address of the first record in the list. The field is updated by the 
GETLINE and PUTGET service routines. 

Reserved. 



Figure 12-8. The List Source Descriptor 

If you have provided an LSD, and specified the STORAGE operand in the 
STACK macro instruction, the second word of the stack parameter block will 
contain the address of the LSD, and the STACK control block structure will look 
like Figure 12-9. 
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Figure 12-9. STACK Control Blocks: In-Storage List Specified 
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Figure 12-10 is an example of the code required to use the STACK macro 
instruction to place a pointer to an in-storage list on the input stack. 

In the example, the GETMAIN macro instruction is used to obtain storage in 
subpool 78 for the list source descriptor and the in-storage list itself. The execute 
form of the STACK macro instruction initializes the input/output parameter list 
required by the STACK service routine. The list form of the STACK macro 
instruction expands into a STACK parameter block, and its address is passed to 
the STACK service routine via the PARM operand in the execute form of the 
STACK macro instruction. 



* 






T 


H 


/ 


S 




c 





o 


£ 




A 


Si 


*U 


u 


£ 


S 




£ 


IV 


T 


/? 


y 




p~ 


X 


o% 


t 


r 


*} 


p 


- 




/P 


£ 


G 


/ 


s 


T 


£ 


P 







fV 


£ 


C 


O 


V 


T 


A 


/ 


/v 


s 




f 






r 


H 


€ 




A 


D 





p 


y 


S 


S 


i 


f 




r 


y 


£ 




£ 


a 


\4 


a 


A 


Ay 


O 


c 


>* 





c 


£1 


>S 





P 




P 


A 


* 


A 


M 


£ 


7 


£ 


p 


L 


/ 


s 


T 


. 












* 














































































































# 


# 


















H 


o 





S 


£ 


«l 


z £ 


p 


/ 


A/ 


5 










































































* 


















A 


D 


D 


R 


£ 


Si 


>A 


B 


/ 


L 


/ 


T 


Y 






































































# 


















S 


A 


V 


E 




Ah 


?£ 


A 




c 


«/ 


A 


1 


w 


/ 


A/ 


G 






























































* 














































































































*• 




















L 


R 










) 


1 
























< 


>A 


V 


£ 


? 


r v 


£ 




A 





D 


P 


£ 


5 


5 







F 


7 


**/ 


c 
















# 
























































c 


■o 


M 


M 


A\ 


/p 




f 


<e 


O 


C 


£ 


S 


S 





R 




P 


Ak 


?A 


M 


e 


r 


£ 


P. 








* 
























































I 


./ 


S 


r 


. 


































































U 


S 


/ 


N 


G 


C 


'P 


P 


j. 


> 


2 


















< 


>£ 


T 




vt 


3 


A 


f 


D 


R 


£ 


5 


5 


A 


B 


/ 


L 


1 


7) 


/ 


\F 





p 




7 


H 


£ 




* 
























































c 


'P 


P 


L 




































































L 












h 


c 


p 


p 


L 


U 


P 


T 












/ 


*L 


A 


C 


£ 


T 


H 


£ 




A 


D 


D 


Z 


£ 


5 


S 







P 


r 


V 


£ 







P 


7 






























































/ 


V 


T 


o 


* 




P 


f 


G 


/ 


S 


T 


£ 


P 


. 














































L 










9 


<> 


c 


p 


p 


L 


£ 


C 


7 












/ 


=Z 


A 


c 


£ 


r 


W 


£ 




A 





D 


f 


£ 


S 


S 




O 


F 


7 


y 


£ 




€ 


C 


7 






* 
























































y 


' ty 


T 


o 


+ 


1 


P 


£ 


G 


/ 


S 


7 


£ 


be 






























* 














































































































* 


* 






/ 


S 


5 


u 


£ 




A 




& 


£ 


7 


W* 


?/ 


y 




F 





# 




S 


u 


6 


P 








L 


7 


B 


. 




7 


// 


£ 




L 


/ 


S 


r 




s 





U 


€ 


CL 




















* 






P 


£ 


S 


c 


f 


/ 


P 


7 





f 




Ah 


JD 




r 


V 


£ 




/, 


V 




5 


r 





tf 


4( 


9£ 




\L 


/ i 


ST 




/ 


r 


S 


f 


\L 


F 




y 





5 


7 


i 


IE 




L 





C 


H 


7 


£ 


O 


* 






/ 


V 




s 


U 


8 


P 








L 




71 


J. 


















































































* 














































































































* 




















6 


£ 


T 


M 


A 


/ \ 


f 








L 





> 


L 


A 


* 


e 


£ 


<s? 


Ui 


=S 


r 


,1 


A' 


>4 


V 


S 


w 


£ 


d 




S 


p 


s 


7 


3 


} 


Lt 


■>c 


s 


B 


£ 


L 


o 


w 






* 














































































































# 


M 














































































































* 


* 









6 


r 


A 


/ 


V 




7 


H 


£ 




AC 


>P, 


^ 


£ 


5 


S 




/ 


V 




5 


>j 


3 


P 


oc 


)L 




7 


8 


F 





P 




r 


</ 


B 




L 


/ 


S 


r 




Si 


to 


e 


C 


J 












* 









£ 


5 


c 


f? 


/ 


o 


T 





P 




Ah 


10 




U 





V 


E 




T 


d 


£ 




L 


S 


D 


/ 


V 


T 


o 


r 


V 


4 


T 




A 


P 


£ 


A 






























* 














































































































# 




















L 










i 


s, 


A 


hi 


S 


w 


a 


R\ 
























































































M 


V 


C 






i 


u 


1 


6 


? 


5 


) 


i 


A 


N 


L 


s 


D 




























































# 














































































































* 


# 









B 


r 


A 


/ 


>V 




r 


H 


£ 




Al 


ID 


p 


£ 


s 


s 




/ 


V 




S 


{/ 


3 


P 


0( 


1L 




7 


8 


F 





P 




7 


H 


£ 




/ 


V 


- 


s 


r 


0* 


?A 


6 


£ 




L 


/ 


s 


7 




# 






A 


H 


D 


, 


u 





V 


£ 




7 


H 


£ 


/ 


V 


- 


s 


T. 





e 


A 


6 


£ 




L 


I 


5/ 


r 


/ 


Kf 


rt 


•) 


T 


H 


A 


T 




A 


P 


£ 


A 




























* 














































































































* 




















L 










( 


• > 


A 


N 


s 


W 


£ 


e 


+ 


<A 




















































































S 


T 








i 


h 





( 


f 


) 




















ST 





R 


£ 


r 


H 


E 




* 


D 


D 


P 


E 


s 


s 







F 


7 


y 


£ 




/ 


V 


























S 


T 








i 


» } 


8 


( 


5 


) 


















i 


sr 


o 


e 


At 


Z£ 




L 


/ 


5 


r 




/ 


V 


r 







r 


Hi 





F 


/ 


£ 


L 


D 


s 







Figure 12-10 (Part 1 of 3). Coding Example - STACK Specifying an In-Storage List as the Input Source 
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Return Codes from STACK 



When it returns to the program which invoked it, the STACK service routine will 
provide one of the following return codes in general register 15: 



Code 



4 



12 
16 
20 



Meaning 

STACK has completed successfully. 

One or more of the parameters passed to STACK were invalid. 

INDD was specified and the file could not be opened. 

OUTDD was specified and the file could not be opened. 

MEMBER was specified but was not in the partitioned data set specified by INDD. 

GETMAIN failure (only possible if MEMBER is specified). 
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GETLINE - Getting a Line of Input 



You use the GETLINE macro instruction to obtain all input lines other than 
commands or subcommands, and prompt message responses. Commands, 
subcommands, and prompt message responses should be obtained with the 
PUTGET macro instruction. 

When a GETLINE macro instruction is executed, a line is obtained from the 
current source of input (the terminal or an in-storage list) or optionally, from the 
terminal, regardless of the current source of input. The processing of the input 
line varies according to several factors. Included in these factors are the source of 
input, and the options you specify for logical or physical processing of the input 
line. The GETLINE service routine determines the type of processing to be 
performed from the operands coded in the GETLINE macro instruction, and 
returns a line of input. 

This topic describes: 

• The list and execute forms of the GETLINE macro instruction 

• The sources of input 

• The GETLINE parameter block 

• The input line format 

• Examples of GETLINE 

• Return codes from GETLINE 



The GETLINE Macro Instruction - List Form 



The list form of the GETLINE macro instruction builds and initializes a 
GETLINE parameter block (GTPB), according to the operands you specify in the 
GETLINE macro. The GETLINE parameter block indicates to the GETLINE 
service routine which functions you want performed. Figure 12-11 shows the list 
form of the GETLINE macro instruction; each of the operands is explained 
following the figure. Appendix A describes the notation used to define macro 
instructions. 



[symbol] 



GETLINE 



INPUT=( ( istack ) (, LOGICAL X) 



■w 



JTERM f\, PHYSICAL J 

, TERMGET= ( ( EDIT ) f , WAIT \)~] ,MF=L 
JASISJ |,NOWAIT f 



Figure 12-11. The List Form of the GETLINE Macro Instruction 

INPUT = 

Indicates that an input line is to be obtained. That input line is further 
described by the INPUT sublist operands ISTACK, TERM, LOGICAL, 
and PHYSICAL. ISTACK and LOGICAL are the default values. 

ISTACK 

Obtain an input line from the currently active input source indicated by the 
input stack. 
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TERM 

Obtain an input line from the terminal. If TERM is coded in the macro 
instruction, the input stack is ignored and regardless of the currently active 
input source, a line is returned from the terminal. 

LOGICAL 

The input line to be obtained is a logical line; the GETLINE service routine 
is to perform logical line processing. 

PHYSICAL 

The input line to be obtained is a physical line. The GETLINE service 
routine need not inspect the input line. 

Note: If the input line you are requesting is a logical line coming from the 
input source indicated by the input stack, you need not code the INPUT 
operand or its sub-list operands. The input line description defaults to 
ISTACK, LOGICAL. 

TERMGET 

Specifies the TGET options requested. GETLINE issues a TGET SVC to 
bring in a line of data from the terminal. This operand indicates to the 
TGET SVC which of the TGET options to use. The TGET options are 
EDIT or ASIS, and WAIT or NOWAIT. The default values are EDIT and 
WAIT. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the buffer is to be 
filled out with trailing blanks. 

ASIS 

Specifies that minimal editing is to be done as follows: 

1 . Transmission control characters are removed. 

2. The line of input is translated from terminal code to EBCDIC. 

3. Line deletion and character deletion editing is performed. 

4. Line feed and carrier return characters, if present, are removed. 

No line continuation checking is done. 

WAIT 

Specifies that control is to be returned to the routine that issued the 
GETLINE macro instruction only after an input message has been read. 

NOWAIT 

Specifies that control is to be returned to the routine that issued the 
GETLINE macro instruction whether or not a line of input is available. If 
a line of input is not available, a return code of 12 decimal is returned in 
register 1 5 to the command processor. 
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MF = L 

Indicates that this is the list form of the macro instruction. 

Note: In the list form of the macro instruction, only 



GETLINE MF=L 



is required. The other operands and their sublists are optional because they may 
be supplied by the execute form of the macro instruction, or automatically 
supplied if you want the default values. 

The operands you specify in the list form of the GETLINE macro instruction set 
up control information used by the GETLINE service routine. The INPUT and 
TERMGET operands set bits in the GETLINE parameter block to indicate to the 
GETLINE service routine which options you want performed. 



The GETLINE Macro Instruction - Execute Form 



Use the execute form of the GETLINE macro instruction to perform the 
following three functions: 

1 . You may use it to set up the input/output parameter list (IOPL). 

2. You may use it to initialize those fields of the GETLINE parameter block 
(GTPB) not initialized by the list form of the macro instruction, or to modify 
those fields already initialized. 

3. You use it to pass control to the GETLINE service routine which gets the 
line of input. 

Figure 12-12 shows the execute form of the GETLINE macro instruction; each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



[symbol] 



GETLINE 



[PARM=parameter address] [ ,UPT=upt address) 

' ,ECT=ect address] [ ,ECB=ecb address) 

,INPUT=( f lSTACK H, LOGICAL \)1 
(TERM j |, PHYSICAL J" J 

,TERMGET=(f EDIT ) J, WAIT ))~| 
(ASISJ |,NOWAIT J 

,ENTRY= /entry address} ~j,MF= (E , (list address)) 

t < 15 > fj \ (1 » / 



Figure 12-12. The Execute Form of the GETLINE Macro Instruction 



PARM = parameter address 

Specifies the address of the 2-word GETLINE parameter block (GTPB). It 
may be the address of a list form GETLINE macro instruction. The 
address is any address valid in an RX instruction, or the number of one of 
the general registers 2-12 enclosed in parentheses. This address will be 
placed in the input/output parameter list (IOPL). 
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UPT = upt address 

Specifies the address of the user profile table (UPT). You may obtain this 
address from the command processor parameter list pointed to by register 1 
when the command processor is attached by the terminal monitor program. 
The address may be any address valid in an RX instruction or the number 
of one of the general registers 2-12 enclosed in parentheses. This address 
will be placed in the IOPL. 

ECT = ect address 

Specifies the address of the environment control table (ECT). You may 
obtain this address from the CPPL pointed to by register 1 when the 
command processor is attached by the terminal monitor program. The 
address may be any address valid in an RX instruction or the number of 
one of the general registers 2-12 enclosed in parentheses. This address will 
be placed into the IOPL. 

ECB = ecb address 

Specifies the address of an event control block (ECB). You must provide a 
one- word event control block and pass its address to the GETLINE service 
routine by placing it into the IOPL. The address may be any address valid 
in an RX instruction or the number of one of the general registers 2-12 
enclosed in parentheses. This address will be placed into the IOPL. 

INPUT = 

Indicates that an input line is to be obtained. This input line is further 
described by the INPUT sublist operands ISTACK, TERM, LOGICAL, 
and PHYSICAL. ISTACK and LOGICAL are the default values. 

ISTACK 

Obtain an input line from the currently active input source indicated by the 
input stack. 

TERM 

Obtain an input line from the terminal. If TERM is coded in the macro 
instruction, the input stack will be ignored and regardless of the currently 
active input source, a line is returned from the terminal. 

LOGICAL 

The input line to be obtained is a logical line; the GETLINE service routine 
is to perform logical line processing. A logical line is a line that has had 
additional processing by the GETLINE service routine before it is returned 
to the requesting program. 

PHYSICAL 

The input line to be obtained is a physical line. A physical line is a line that 
is returned to the requesting program exactly as it is received from the input 
source. 

Note: If the input line you are requesting is a logical line coming from the 
input source indicated by the input stack, you need not code the INPUT 
operand or its sublist operands. The input line description defaults to 
ISTACK, LOGICAL. 
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TERMGET 

Specifies the TGET options requested. GETLINE issues a TGET SVC to 
bring in a line of data from the terminal. This operand indicates to the 
TGET SVC which of the TGET options to use. The TGET options are 
EDIT or ASIS, and WAIT or NOWAIT. The default values are EDIT and 
WAIT. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the input buffer is 
to be filled out with trailing blanks. All station control characters are 
suppressed from data. 

ASIS 

Specifies that minimal editing is to be done by the TGET SVC. The 
following editing functions will be performed by TGET: 

1. Station control characters remain in the data. 

2. The line of input is translated from terminal code to EBCDIC. 

3. Line deletion and character deletion editing are performed. 

4. Line feed and carrier return characters, if present, are removed. 

No line continuation checking is done. 

WAIT 

Specifies that control is to be returned to the routine that issued the 
GETLINE macro instruction, only after an input message has been read. 

NOWAIT 

Specifies that control is to be returned to the routine that issued the 
GETLINE macro instruction whether or not a line of input is available. If 
a line of input is not available, a return code of 12 decimal is returned in 
register 15 to the command processor. 

ENTRY = entry address or (15) 

Specifies the entry point of the GETLINE service routine. If ENTRY is 
omitted, a LINK macro instruction will be generated to invoke the 
GETLINE service routine. The address may be any address valid in an RX 
instruction or (15) if the entry point address has been loaded into general 
register 15. 

MF = E 

Indicates that this is the execute form of the macro instruction. 

listaddr 

(1) 

The address of the four-word input/output parameter list (IOPL). This may 
be a completed IOPL that you have built, or it may be 4 words of declared 
storage that will be filled from the PARM, UPT, ECB, and ECT operands 
of this execute form of the GETLINE macro instruction. The address is 
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any address valid in an RX instruction or (1) if the parameter list address 
has been loaded into general register 1 . 

Note: In the execute form of the GETLINE macro instruction only the following 
is required: 



GETLINE 



MF=(E 



,flist address)) 

\ (1) f 



Sources of Input 



The PARM, UPT, ECT, and ECB operands are not required if you have built 
your IOPL in your own code. The other operands and their sublists are optional 
because you may have supplied them in the list form of the macro instruction or 
in a previous execution of GETLINE, or because you are using the default values. 

The ENTRY operand need not be coded in the macro instruction. If it is not, a 
LINK macro instruction will be generated to invoke the I/O service routine. 

The operands you specify in the execute form of the GETLINE macro instruction 
are used to set up control information used by the GETLINE service routine. 
You can use the PARM, UPT, ECT, and ECB operands of the GETLINE macro 
instruction to build, complete, or modify an IOPL. The INPUT and TERMGET 
operands set bits in the GETLINE parameter block. These bit settings indicate to 
the GETLINE service routine which options you want performed. 



There are two sources of input provided; they are the terminal, and an in-storage 
list. 

1 . Terminal: Input comes from the terminal under either of the following 
conditions: 

• You have specified the terminal as the input source by including the 
TERM operand in the GETLINE macro instruction. 

• You have specified the current element of the input stack by including the 
ISTACK operand in the GETLINE macro instruction, and the current 
element is a terminal element. 

If you specify terminal as the input source, you have the option of requesting 
the GETLINE service routine to process the input as a logical or physical line 
by including the LOGICAL or the PHYSICAL operand in the macro 
instruction. LOGICAL is the default value. 

Physical Line Processing: A physical line is a line that is returned to the 
requesting program exactly as it is received from the input source. The 
contents of the line are not inspected by the GETLINE service routine. 

Logical Line Processing: A logical line is a line that has undergone additional 
processing by the GETLINE service routine before it is returned to the 
requesting program. If logical line processing is requested, each line returned 
to the routine that issued the GETLINE is inspected to see if the last 
character of the line is a continuation mark (a dash '-' or a plus ' + ')• A 
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End of Data Processing 



continuation mark signals GETLINE to get another line from the terminal 
and to concatenate that line with the line previously obtained. The 
continuation mark is overlaid with the first character of the new line. 
However, ASIS does not recognize line continuation. 

In-Storage List: If the top element of the input stack is an in-storage list, and 
you do not specify TERM in the GETLINE macro instruction, the line will 
be obtained from the in-storage list. The in-storage list is a resident data set 
that has been previously made available to the I/O service routines with the 
STACK service routine. The STACK service routine saves the addressing 
mode of the program that invoked it. Address values will be treated as 24-bit 
or 31 -bit addressing mode depending on the original issuer of STACK for 
that element. No logical line processing is performed on the lines because it is 
assumed that each line in the in-storage list is a logical line. It is also 
assumed that no single record has a length greater than 256 bytes. 



If you issue a GETLINE macro against an in-storage list from which all the 
records have already been read, GETLINE senses an end of data (EOD) 
condition. GETLINE deletes the top element from the input stack and passes a 
return code of 16 in register 15. Return code 16 indicates that no line of input 
has been returned by the GETLINE service routine. You can use this EOD code 
(16) as an indication that all input from a particular source has been exhausted 
and no more GETLINE macro instructions should be issued against this input 
source. If you reissue a GETLINE macro instruction against the input stack after 
a return code of 16, a record will be returned from the next input source indicated 
by the input stack. You can identify the source of this record by the return code 
(0 = terminal, 4 = in-storage). 



Building the GETLINE Parameter Block 



When the list form of the GETLINE macro instruction expands, it builds a two 
word GETLINE parameter block (GTPB). The list form of the macro instruction 
initializes this GTPB according to the operands you have coded in the macro 
instruction. This initialized block, which you may later modify with the execute 
form of the macro instruction, indicates to the GETLINE service routine the 
function you want performed. 

You must supply the address of the GTPB to the execute form of the GETLINE 
macro instruction. For non-reenterable programs you can do this simply by 
placing a symbolic name in the symbol field of the list form of the macro 
instruction, and passing this symbolic name to the execute form of the macro 
instruction as the PARM value. The GETLINE parameter block is defined by 
the IKJGTPB DSECT. Figure 12-13 describes the contents of the GTPB. 
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Number 
of Bytes 


Field 


Contents or Meaning 


2 




Control flags. These bits describe the requested input line to the 
GETLINE service routine. 




Byte 1 
..0 


The input line is a logical line. 




..1 


The input line is a physical line. 




...0 .... 


The input line is to be obtained from the current input source indicated 
by the input stack. 




...1 .... 


The input line is to be obtained from the terminal. 




XX.. xxxx 


Reserved bits. 




Byte 2 
xxxx xxxx 


Reserved. 


2 




TGET options field. These bits indicate to the TGET SVC which of the 
TGET options you want to use. 




Byte 1 
1 


Always set to 1 for TGET. 




...0 .... 


WAIT processing has been requested. Control will be returned to the 
issuer of GETLINE only after an input message has been read. 




...1 .... 


NOWAIT processing has been requested. Control will be returned to 
the issuer of the GETLINE macro instruction whether or not a line of 
input is available. 




00 


EDIT processing has been requested. In addition to the editing 
provided by ASIS processing, the input buffer is to be filled out with 
trailing blanks to the next doubleword boundary. 




01 


ASIS processing has been requested. (See the ASIS operand of the 
GETLINE macro instruction description.) 




.XX. XX.. 


Reserved bits. 




Byte 2 
xxxx xxxx 


Reserved. 


4 


GTPBIBUF 


The address of the input buffer. The GETLINE service routine fills this 
field with the address of the input buffer in which the input line has 
been placed. 



Figure 12-13. The GETLINE Parameter Block 



Input Line Format - The Input Buffer 



The second word of the GETLINE parameter block contains zeros until the 
GETLINE service routine returns a line of input. The service routine places the 
requested input line into an input buffer beginning on a doubleword boundary 
located in subpool 1 . It then places the address of this input buffer into the 
second word of the GTPB. The input buffer belongs to the command processor 
that issued the GETLINE macro instruction. The buffers returned by GETLINE 
are automatically freed when your CP relinquishes control. You may free the 
input buffer with the FREEMAIN macro instruction after you have processed or 
copied the input line. 

Regardless of the source of input, an in-storage list or the terminal, the input line 
returned to the command processor by the GETLINE service routine is in a 
standard format. All input lines are in a variable length record format with a 
fullword header followed by the text returned by GETLINE. Figure 12-14 shows 
the format of the input buffer returned by the GETLINE service routine. 
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Figure 12-14. Format of the GETLINE Input Buffer 



The two-byte length field contains the length of the input line including the 
header length (4 bytes). You can use the length field to determine the length of 
the input line to be processed, and later, to free the input buffer with the R-form 
of the FREEMAIN macro instruction. 

The two-byte offset field is always set to zero on return from the GETLINE 
service routine. 

Figure 12-15 shows the GETLINE control block structure after the GETLINE 
service routine has returned an input line. 
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Figure 12-15. GETLINE Control Blocks - Input Line Returned 



Examples of GETLINE 



Figure 12-16 is an example of the code required to execute the GETLINE macro 
instruction. In this example two execute forms of the GETLINE macro 
instruction are issued. The first one builds the IOPL, and uses the parameters 
initialized by the list form of the macro instruction to get a physical line from the 
terminal with the NOW AIT and ASIS options. 

In the second execution of the GETLINE macro instruction, the same IOPL is 
used, but the GETLINE options are changed explicitly from TERM to ISTACK 
and from NOWAIT to WAIT, and by default from PHYSICAL to LOGICAL 
and from ASIS to EDIT. 



Notice also that the IKJCPPL DSECT is used to map the command processor 
parameter list, and the IKJGTPB DSECT is used to map the GETLINE 
parameter block. 
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Figure 12-16 (Part 1 of 2). Coding Example - Two Executions of GETLINE 
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Figure 12-16 (Part 2 of 2). Coding Example - Two Executions of GETLINE 



Return Codes from GETLINE 



When it returns to the program that invoked it, the GETLINE service routine 
returns one of the following codes in general register 15: 

Code Meaning 

GETLINE has completed successfully. The line was obtained from the terminal. 

4 GETLINE has completed successfully. The line was returned from an in-storage list. 

8 The GETLINE function was not completed. An attention interruption occurred during 

GETLINE processing, and the user's attention routine turned on the completion bit in the 
communications ECB. 

12 The NO WAIT option was specified and no line was obtained. 
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16 EOD - An attempt was made to get a line from an in-storage list but the list had been 

exhausted. 

20 Invalid parameters passed to the GETLINE service routine. 

24 A conditional GETMAIN was issued by GETLINE for input buffers and there was not 

sufficient space to satisfy the request. 

28 The terminal has been disconnected. 

32 An attempt to obtain a line from a command procedure DATA-ENDDATA group failed. 

36 End of data was received when a continuation condition was expected. 



PUTLINE - Putting a Line Out to the Terminal 



Use the PUTLINE macro instruction to prepare a line and write it to the 
terminal. Use PUTLINE to put out lines that do not require immediate response 
from the terminal; use PUTGET to put out lines that require immediate response. 
The types of lines which do not require response from the terminal are defined as 
data lines and informational message lines. 

The PUTLINE service routine prepares a line for output according to the 
operands you code into the list and execute forms of the PUTLINE macro 
instruction. The operands of the macro instruction indicate to the PUTLINE 
service routine the type of line being put out (data line or informational message 
line), the type of processing to be performed on the line (format only, second level 
informational message chaining, text insertion), and the TPUT options requested. 

This topic describes: 

• The list and execute forms of the PUTLINE macro instruction 

• The PUTLINE parameter block 

• The types and formats of output lines 

• PUTLINE message processing 

• Return codes from PUTLINE 

Coding examples are included where appropriate. 
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The PUTLINE Macro Instruction - List Form 



The list form of the PUTLINE macro instruction builds and initializes a 
PUTLINE parameter block (PTPB), according to the operands you specify in the 
macro instruction. The PUTLINE parameter block indicates to the PUTLINE 
service routine which functions you want performed. Figure 12-17 shows the list 
form of the PUTLINE macro instruction; each of the operands is explained 
following the figure. Appendix A describes the notation used to define macro 
instructions. 



[symbol] 


PUTLINE 




(, SINGLE I 
OUTPUT=( output address (, TERM ) , MULTLVL {, INFOR 

\ format/ (,multlin) ^,data 

= (EDIT I I 

,termput=( asis (,wait W,nohold1 (,nobreak) ) 
( control ) \, nowait f \, hold / \, breakin j 

,MF=L 


i 





Figure 12-17. The List Form of the PUTLINE Macro Instruction 



OUTPUT = output address 

Indicates that an output line is to be written to the terminal. The type of 
line provided and the processing to be performed on that line by the 
PUTLINE service routine are described by the OUTPUT sublist operands 
TERM, FORMAT, SINGLE, MULTLVL, MULTLIN, INFOR and 
DATA. The default values are TERM, SINGLE, and INFOR. The output 
address differs depending upon whether the output line is an informational 
message or a data line. For DATA requests, it is the address of the 
beginning (the fullword header) of a data record to be written to the 
terminal. For informational message requests (INFOR), it is the address of 
the output line descriptor. The output line descriptor (OLD) describes the 
message to be put out, and contains the address of the beginning (the 
fullword header) of the message or messages to be written to the terminal by 
the PUTLINE service routine. 

TERM 

Write the line out to the terminal. 

FORMAT 

The output request is only to format a single message and not to put the 
message out to the terminal. The PUTLINE service routine returns the 
address of the formatted line by placing it in the third word of the 
PUTLINE parameter block. 

SINGLE 

The output line is a single line. 

MULTLVL 

The output message consists of multiple levels. INFOR must be specified. 
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MULTLIN 

The output data consists of multiple lines. DATA must be specified. 

INFOR 

The output line is an informational message. 

DATA 

The output line is a data line. 

TERMPUT 

Specifies the TPUT options requested. PUTLINE issues a TPUT SVC to 
write the line to the terminal. This operand indicates which of the TPUT 
options you want to use. The TPUT options are EDIT, ASIS, or 
CONTROL; WAIT or NOWAIT; NOHOLD or HOLD; and NOBREAK 
or BREAKIN. The default values are EDIT, WAIT, NOHOLD, and 
NOBREAK. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the following TPUT 
functions are requested: 

1 . Any trailing blanks are removed before the line is written to the 
terminal. If a blank line is sent, the terminal vertically spaces one line. 

2. Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 

3. All terminal control characters (for example: bypass, restore, horizontal 
tab, new line) are replaced with a printable character. Backspace is an 
exception; see item 4 under ASIS. 

ASIS 

Specifies that minimal editing is to be performed by TPUT as follows: 

1. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to prevent 
program-caused I/O errors. This does not mean that all unprintable 
characters are eliminated. Restore, upper case, lower case, bypass, and 
bell ring, for example, might be valid but nonprinting characters at 
some terminals. (See CONTROL.) 

2. Transmission control characters are added. 

3. EBCDIC NL, placed at the end of the message, indicates to the TPUT 
SVC that the cursor is to be returned at the end of the line. NL is 
replaced with whatever is necessary for that particular terminal type to 
cause the cursor to return. This NL processing occurs only if you 
specify ASIS, and the NL is the last character in your message. 

If you specify EDIT, NL is handled as described by item 3 under EDIT. 

If the NL is embedded in your message, it is sent to the terminal as a 
carrier return. No idle characters are added (see item 6 below). This 
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may cause overprinting, particularly on terminals that require a line-feed 
character to position the carrier on a new line. 

4. If you have used backspace in your output message, but the backspace 
character does not exist on the terminal type to which the message is 
being routed, TPUT attempts alternate methods to accomplish the 
backspace. 

5. Control characters are added as needed to cause the message to occur 
on several lines if the output line is longer than the terminal line size. 

6. Idle characters are sent at the end of each line to prevent typing as the 
carrier returns. 

CONTROL 

Specifies that the output line is composed of terminal control characters and 
will not print or move the carrier on the terminal. This option should be 
used for transmission of characters such as bypass, restore, or bell ring. 

WAIT 

Specifies that control will not be returned until the output line has been 
placed into a terminal output buffer. 

NOWAIT 

Specifies that control should be returned whether or not a terminal output 
buffer is available. If no buffer is available, a return code of 8 (decimal) 
will be returned in register 15 to the command processor. 

NOHOLD 

Specifies that control is to be returned to the routine that issued the 
PUTLINE macro instruction, and that the routine can continue processing 
as soon as the output line has been placed on the output queue. 

HOLD 

Specifies that the routine that issued the PUTLINE macro instruction 
cannot continue its processing until this output line has been put out to the 
terminal or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, the user is not 
to be interrupted. The output message is placed on the output queue to be 
printed after the terminal user has completed the line. 

BREAKIN 

Specifies that output has precedence over input. If the user at the terminal 
is transmitting, he is interrupted, and this output line is sent. Any data that 
was received before the interruption is kept and displayed at the terminal 
following this output line. 
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MF = L 

Indicates that this is the list form of the macro instruction. 

Note: In the list form of the macro instruction, only 



PUTLINE MF=L 



is required. The output line address is required for each issuance of the 
PUTLINE macro instruction but it may be supplied in the execute form of the 
macro instruction. 

The other operands and sublists are optional because you can supply them in the 
execute form of the macro instruction, or they will be supplied by the macro 
expansion if you want the default values. 

The operands you specify in the list form of the PUTLINE macro instruction set 
up control information used by the PUTLINE service routine. This control 
information is passed to the PUTLINE service routine in the PUTLINE 
parameter block, a three-word parameter block built and initialized by the list 
form of the PUTLINE macro instruction. 



The PUTLINE Macro Instruction - Execute Form 



Use the execute form of the PUTLINE macro instruction to put a line or lines 
out to the terminal, to chain second level messages, and to format a line and 
return the address of the formatted line to the code that issued the PUTLINE 
macro instruction. The execute form of the PUTLINE macro instruction 
performs the following functions: 

1 . It can be used to set up the input/output parameter list (IOPL). 

2. It can be used to initialize those fields of the PUTLINE parameter block 
(PTPB) not initialized by the list form of the macro instruction, or to modify 
those fields already initialized. 

3. It passes control to the PUTLINE service routine. 

The PUTLINE service routine makes use of the IOPL and the PTPB to determine 
which of the PUTLINE functions you want performed. 
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Figure 12-18 shows the execute form of the PUTLINE macro instruction; each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



[symbol] 



PUTLINE 



[PARM=parameter address] [ ,UPT=upt address) 

[,ECT=ect address] [ ,ECB=ecb address] 

',OUTPUT=( output address f, TERM \ (, SINGLE 

FORMATf j,MULTLVL 
,MULTLIN 

infor\) 



{■ 



( EDIT 
,TERMPUT=( AS IS J 
CONTROL 



(,DATA j 
f, WAIT ) i. NOHOLP ) (, NOBREAK \) 



,ENTRY=Jentry address 
\ (15) 



I,] . 

(,nowait|^,hold /^breakin f J 
)~|,MF=(E,jlist address)) 

11 l (1) f 



Figure 12-18. The Execute Form of the PUTLINE Macro Instruction 



PARM = parameter address 

Specifies the address of the 3 -word PUTLINE parameter block (PTPB). It 
may be the address of a list form of the PUTLINE macro instruction. The 
address is any address in an RX instruction, or the number of one of the 
general registers 2-12 enclosed in parentheses. This address will be placed 
into the IOPL. 

UPT = upt address 

Specifies the address of the user profile table (UPT). You may obtain this 
address from the command processor parameter list (CPPL) pointed to by 
register 1 when a command processor is attached by the terminal monitor 
program. The address may be any address valid in an RX instruction or it 
may be placed in one of the general registers 2-12 and the register number 
enclosed in parentheses. This address will be placed into the IOPL. 

ECT = ect address 

Specifies the address of the environment control table (ECT). You may 
obtain this address from the CPPL pointed to by register 1 when a 
command processor is attached by the terminal monitor program. The 
address may be any address valid in an RX instruction or it may be placed 
in one of the general registers 2-12 and the register number enclosed in 
parentheses. This address will be placed into the IOPL. 

ECB = ecb address 

Specifies the address of the event control block (ECB). You must provide a 
one-word event control block and pass its address to the PUTLINE service 
routine. This address will be placed into the IOPL. The address may be 
any address valid in an RX instruction or it may be placed in one of the 
general registers 2-12 and the register number enclosed in parentheses. 

OUTPUT = output address 

Indicates that an output line is provided. The type of line provided and the 
processing to be performed on that line by the PUTLINE service routine are 
described by the OUTPUT sublist operands TERM, FORMAT, SINGLE 
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MULTLVL, MULTLIN, INFOR and DATA. The default values are 
TERM, SINGLE, and INFOR. 

The output address differs depending upon whether the output line is an 
informational message or a data line. For DATA requests, it is the address 
of the beginning (the fullword header) of a data record to be put out to the 
terminal. For informational message requests (INFOR), it is the address of 
the output line descriptor. The output line descriptor (OLD) describes the 
message to be put out, and contains the address of the beginning (the 
fullword header) of the message or messages to be written to the terminal by 
the PUTLINE service routine. 

TERM 

Write the line out to the terminal. 

FORMAT 

The output request is only to format a single message and not to put the 
messages out to the terminal. The PUTLINE service routine returns the 
address of the formatted line by placing it in the third word of the 
PUTLINE parameter block. 



SINGLE 

The output line is a single line. 



MULTLVL 

The output message consists of multiple levels. INFOR must be specified. 

MULTLIN 

The output data consists of multiple lines. DATA must be specified. 

INFOR 

The output line is an informational message. 

DATA 

The output line is a data line. 

TERMPUT 

Specifies the TPUT options requested. PUTLINE issues a TPUT SVC to 
write the line to the terminal. This operand indicates which of the TPUT 
options you want to use. The TPUT options are EDIT, ASIS, or 
CONTROL; WAIT or NOWAIT; NOHOLD or HOLD; and NOBREAK 
or BREAKIN. The default values are EDIT, WAIT, NOHOLD, and 
NOBREAK. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the following TPUT 
functions are requested: 

1. Any trailing blanks are removed before the line is written to the 
terminal. If a blank line is sent, the terminal vertically spaces one line. 

2. Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 



Chapter 12. Using the TSO I/O Service Routines for Terminal I/O 12-39 



3. All terminal control characters (for example: bypass, restore, horizontal 
tab, new line) are replaced with a printable character. Backspace is an 
exception; see item 4 under ASIS. 

ASIS 

Specifies that minimal editing is to be performed by TPUT as follows: 

1. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to prevent 
program-caused I/O errors. This does not mean that all unprintable 
characters are eliminated. Restore, upper case, lower case, bypass, and 
bell ring, for example, may be valid but nonprinting characters at some 
terminals. (See CONTROL.) 

2. Transmission control characters are added. 

3. EBCDIC NL, placed at the end of the message, indicates to the TPUT 
SVC that the cursor is to be returned at the end of the line. NL is 
replaced with whatever is necessary for that particular terminal type to 
cause the cursor to return. This NL processing occurs only if you 
specify ASIS, and the NL is the last character in your message. 

If you specify EDIT, NL is handled as described in 3 under EDIT. 

If the NL is embedded in your message, a semicolon is substituted for 
NL and sent to the terminal. No idle characters are added (see item 6 
below). This may cause overprinting, particularly on terminals that 
require a line-feed character to position the cursor on a new line. 

4. If you have used backspace in your output message, but the backspace 
character does not exist on the terminal type to which the message is 
being routed, the PUTLINE service routine attempts alternate methods 
to accomplish the backspace. 

5. Control characters are added as needed to cause the message to occur 
on several lines if the output line is longer than the terminal line size. 

6. Idle characters are sent at the end of each line to prevent typing as the 
carrier returns. 

CONTROL 

Specifies that the output line is composed of terminal control characters and 
will not display or move the cursor on the terminal. This option should be 
used for transmission of characters such as bypass, restore, or bell ring. 

WAIT 

Specifies that control will not be returned until the output line has been 
placed into a terminal output buffer. 

NOWAIT 

Specifies that control should be returned whether or not a terminal output 
buffer is available. If no buffer is available, a return code of 8 is returned in 
register 15. 
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NOHOLD 

Specifies that control is returned to the routine that issued the PUTLINE 
macro instruction, and it can continue processing, as soon as the output line 
has been placed on the output queue. 

HOLD 

Specifies that the module that issued the PUTLINE macro instruction is not 
to resume processing until the output line has been put out to the terminal 
or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, the user is not 
to be interrupted. The output message is placed on the output queue to be 
displayed after the terminal user has completed the line. 

BREAKIN 

Specifies that output has precedence over input. If the user at the terminal 
is transmitting, the user is interrupted, and the output line is sent. Any data 
that was received before the interruption is kept and displayed at the 
terminal following the output line. 

ENTRY = entry address or (15) 

Specifies the entry point of the PUTLINE service routine. If ENTRY is 
omitted, the PUTLINE macro expansion will generate a LINK macro 
instruction to invoke the PUTLINE service routine. The address may be 
any address valid in an RX instruction or (15) if the entry point address has 
been loaded into general register 15. 

MF = E 

Indicates that this is the execute form of the PUTLINE macro instruction. 

list address 

(1) 

The address of the four-word input/output parameter list (IOPL). This may 
be a completed IOPL that you have built, or 4 words of declared storage to 
be filled from the PARM, UPT, ECT, and ECB operands of this execute 
form of the PUTLINE macro instruction. The address is any address valid 
in an RX instruction or (1) if the parameter list address has been loaded 
into general register 1. 

Note: In the execute form of the PUTLINE macro instruction only the following 
is required: 



PUTLINE 



,(li£ 



MF=(E,(list address 
(1) 



The PARM, UPT, ECT, and ECB operands are not required if you have built, 
your IOPL in your own code. 

The output line address is required for each issuance of the PUTLINE macro 
instruction, but you may supply it in the list form of the macro instruction. 
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The other operands and sublists are optional because you may have supplied them 
in the list form of the macro instruction or in a previous execute form, or because 
you may want to use the default values which are automatically supplied by the 
macro expansion itself. 

The ENTRY operand need not be coded in the macro instruction. If it is not, a 
LINK macro instruction will be generated by the macro expansion to invoke the 
I/O service routine. 

The operands you specify in the execute form of the PUTLINE macro instruction 
set up control information used by the PUTLINE service routine. You can use 
the PARM, UPT, ECT, and ECB operands of the PUTLINE macro instruction 
to build, complete or modify an IOPL. The OUTPUT and TERMPUT operands 
and their sublist operands initialize the PUTLINE parameter block. The 
PUTLINE parameter block is referenced by the PUTLINE service routine to 
determine which functions you want PUTLINE to perform. 



Building the PUTLINE Parameter Block 



When the list form of the PUTLINE macro instruction expands, it builds a 
three-word PUTLINE parameter block (PTPB). The list form of the macro 
instruction initializes the PTPB according to the operands you have coded in the 
macro instruction. The initialized block, which you may later modify with the 
execute form of the PUTLINE macro instruction, indicates to the PUTLINE 
service routine the function you want performed. You must supply the address of 
the PTPB to the execute form of the PUTLINE macro instruction. Since the list 
form of the macro instruction expands into a PTPB, all you need do is pass the 
address of the list form of the macro instruction to the execute form as the 
PARM value. 
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The PUTLINE parameter block is defined by the IKJPTPB DSECT. 
Figure 12-19 describes the contents of the PTPB. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 




Control flags. These bits describe the output line to the PUTLINE 
service routine. 




Byte 1 

..0 

..1 

...1 .... 
.... 1... 

1.. 

1. 

XX X 


The output line is a message. 

The output line is a data line. 

The output line is a single level or a single line. 

The output is multiline. 

The output is multilevel. 

The output line is an informational message. 

Reserved bits. 




Byte 2 

..1 

xx.x xxxx 


The format only function was requested. 
Reserved bits. 


2 




TPUT options field. These bits indicate to the TPUT SVC which of 
the TPUT options you want to use. 




Byte 1 



Always set to for TPUT. 




...0 .... 


WAIT processing has been requested. Control will be returned to the 
issuer of PUTLINE only after the output line has been placed into a 
terminal output buffer. 




...1 .... 


NOW AIT processing has been requested. Control will be returned to 
the issuer of PUTLINE whether or not a terminal output buffer is 
available. 




.... 0... 


NOHOLD processing has been requested. The command processor 
that issued the PUTLINE can resume processing as soon as the output 
line has been placed on the output queue. 




.... 1... 


HOLD processing has been requested. The command processor that 
issued the PUTLINE is not to resume processing until the output line 
has been written to the terminal or deleted. 




0.. 


NOBREAK processing has been requested. The output line will be 
printed only when the terminal user is not entering a line. 




1.. 


BREAKIN processing has been requested. The output line is to be 
sent to the terminal immediately. If the terminal user is entering a line, 
he is to be interrupted. 




00 


EDIT processing has been requested. 




01 


ASIS processing has been requested. 




.... ..10 


CONTROL processing has been requested. 




.XX 


Reserved. 




Byte 2 


Reserved. 


4 


PTPBOPUT 


The address of the output line descriptor (OLD) if the output line is a 
message. The address of the fullword header preceding the data if the 
output line is a single data line. The address of a forward-chain 
pointer preceding the fullword data header, if the output is multiline 
data. 


4 


PTPBFLN 


Address of the format only line. The PUTLINE service routine places 
the address of the formatted line into this field. 



Figure 12-19. The PUTLINE Parameter Block 
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Types and Formats of Output Lines 

There are two types of output lines processed by the PUTLINE service routine: 

• Data lines (DATA) 

• Message lines (INFOR) 

The OUTPUT sublist operands you specify in the PUTLINE macro instruction 
indicate to the PUTLINE service routine which type of line you want processed 
(DATA, INFOR), whether the output consists of one line, several lines, or several 
levels of messages (SINGLE, MULTLIN, MULTLVL), and whether the line is to 
be written to the terminal (TERM), or formatted only (FORMAT). 

1 . Data Lines: A data line is the simplest type of output processed by the 
PUTLINE service routine. It is simply a line of text to be written to the 
terminal. PUTLINE does not format the line or process it in any way; it 
merely writes the line, as it appears, out to the terminal. There are two kinds 
of data lines, single line data and multiline data; each is handled differently 
by the PUTLINE service routine. 

Single Line Data: Single line data is one contiguous character string that 
PUTLINE places out to the terminal as one logical line. If the line of data 
you provide exceeds the terminal line length, the TPUT routine segments the 
line and puts it out as several terminal lines. PUTLINE accepts single line 
data in the format shown in Figure 12-20. 



PUTLINE OUTPUT = (output address, 



, SINGLE, DATA) 




Length 



Offset 



Data 



Length 



Figure 12-20. PUTLINE Single Line Data Format 



You must precede your line of data with a 4-byte header field. The first two 
bytes contain the length of the output line, including the header; the second 
two bytes are reserved for offsets and are set to zero for data lines. You pass 
the address of the output line to the PUTLINE service routine by coding the 
beginning address of the four-byte header as the OUTPUT operand address 
in either the list or the execute form of the macro instruction. When the 
macro instruction expands, it places this data line address into the second 
word of the PUTLINE parameter block. 
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Figure 12-21 is an example of the code that could be used to write a single 
line of data to the terminal using the PUTLINE macro instruction. Note that 
the execute form of the PUTLINE macro instruction is used in this example 
to construct the input/output parameter list, and that the TERMPUT 
operands are not coded in either the list or the execute form of the macro 
instruction; the default values will be assumed by the PUTLINE service 
routine. 
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Figure 12-21. Coding Example - PUTLINE Single Line Data 
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Multiline Data: Multiline data is a chain of single lines. Each line of data is 
processed by the PUTLINE service routine exactly as if it were single line 
data. Each element of the chain, however, begins a new line to the terminal. 
By specifying multiline data (MULTLIN) in the PUTLINE macro 
instruction, you can put out several variable length, non-contiguous lines at 
the terminal with one execution of the macro instruction. PUTLINE accepts 
multiline data in a format similar to that of single line data except that each 
line is prefaced with a fullword forward chain pointer. Figure 12-22 shows 
the format of PUTLINE multiline data. 



PUTLINE OUTPUT - (output address, , MULTLIN, DATA) _ 


_ 








Pointer to next element 


Length 


Offset 


Data \ j 












; 




/ 


Length 










Pointer to next element 


Length 


Offset 


Data ) \ 


















00000000 


Length 


Offset 


Data \ \ 



















Figure 12-22. PUTLINE Multiline Data Format 



Each of the forward-chain pointers points to the next data line to be written 
to the terminal. The forward-chain pointer in the last data line contains 
zeros. In the case of multiline data, you pass the address of the output line to 
the PUTLINE service routine by coding the beginning address of the first 
forward-chain pointer as the OUTPUT operand address in either the list or 
the execute form of the macro instruction. When the macro instruction 
expands, it will place this multiline data address into the second word of the 
PUTLINE parameter block. 



| 
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Figure 12-23 is an example of the code required to write multiple lines of 
data to the terminal using the PUTLINE macro instruction. Note that the 
programmer has built his own IOPL rather than build it with the execute 
form of the PUTLINE macro instruction. Note also the use of the IOPL and 
CPPL DSECTs (generated by the IKJIOPL and IKJCPPL macro 
instructions). These provide an easy method of accessing the fields within the 
IOPL and the CPPL, and they protect your code from changes made to the 
control blocks. 
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Figure 12-23 (Part 1 of 2). Coding Example - PUTLINE Multiline Data 
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Figure 12-23 (Part 2 of 2). Coding Example - PUTLINE Multiline Data 



2. Message Lines: If you code INFOR in the PUTLINE macro instruction, the 
PUTLINE service routine writes the information you supply as an 
informational message and provides additional functions not applicable to 
data lines. An informational message is a line of output from the program in 
control to the user at the terminal. It is used solely to pass output to the 
terminal; no input from the terminal is required after an informational 
message. 

There are two types of informational messages processed by the PUTLINE 
service routine: 

• Single level messages (SINGLE) 

• Multilevel message (MULTLVL) 

Single Level Messages: A single level message is composed of one or more 
message segments to be formatted and written to the terminal with one 
execution of the PUTLINE macro instruction. 

Multilevel Messages: Multilevel messages are composed of one or more 
message segments to be formatted and written to the terminal, and one or 
more message segments to be formatted and placed on an internal chain in 
shared subpool 78. This internal chain can either be put out to the terminal 
or purged by a second execution of the PUTLINE macro instruction. 
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Passing the Message Lines to PUTLINE 



You must build each of the message segments to be processed by the PUTLINE 
service routine as if it were a line of single line data. The segment must be 
preceded by a four-byte header field - the first two bytes containing the length of 
the segment, including the header, and the second two bytes containing zeros or 
an offset value if you use the text insertion facility. See "Using the PUTLINE 
Text Insertion Function" for a discussion of offset values. This message line 
format is required whether the message is a single level message or a multilevel 
message. 

Because of the additional operations performed on message lines, however, you 
must provide the PUTLINE service routine with a description of the line or lines 
that are to be processed. This is done with an output line descriptor (OLD). 

There are two types of output line descriptors, depending on whether the messages 
are single level or multilevel. 

The OLD required for a single level message is a variable-length control block 
which begins with a fullword value representing the number of segments in the 
message, followed by fullword pointers to each of the segments. 

The format of the OLD for multilevel messages varies from that required for 
single level messages in only one respect. You must preface the OLD with a 
fullword forward-chain pointer. This chain pointer points to another output line 
descriptor or contains zero to indicate that it is the last OLD on the chain. 
Figure 12-24 shows the format of the output line descriptor. 



Number 
of Bytes 


Field 


Contents or Meaning 


4 

4 
4 
4 


none 

none 
none 
none 


The address of the next OLD, or zero if this is the last one on the chain. 
This field is present only if the message pointed to is a multilevel 
message. 

The number of message segments pointed to by this OLD. 

The address of the first message segment. 

The address of the next message segment. 



Figure 12-24. The Output Line Descriptor (OLD) 

You must build the output line descriptor and pass its address to the PUTLINE 
service routine as the OUTPUT operand address in either the list or the execute 
form of the macro instruction. When the macro instruction expands, it places the 
address of the output line descriptor into the second word of the PUTLINE 
parameter block. 
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Terminal 
Monitor 
Program 



ATTACH 



Command 
Processor 



LINK 



Reg. 1 



CPPL 




PUTLINE 

Service 

Routine 



Reg. 1 



IOPL 



PTPB 



(OLD 



Single Level Messages 



Number 



f Segment 1 



f Segment 2 



Length 


Offset 


Text 









| Segment n 



From PTPB' 



Mult i- Level Messages 




J Next OLD 



Number 



f Segment 1 



^ Segment 2 



Length 


Offset 


Text 











| Segment n 



00000000 



Number 



f Segment 1 



| Segment 2 



A Segment n 



Figure 12-25. Control Block Structures for PUTLINE Messages 
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PUTLINE Message Line Processing 



In addition to writing a message out to the terminal, the PUTLINE service 
routine provides the following additional functions for message line (INFOR) 
processing: 

• Message identification stripping 

• Text insertion 

• Formatting only 

• Second level informational chaining 

Figure 12-26 shows the distribution of these PUTLINE service routine functions 
over the two output message types. 



Functions 


Message Types 
Single Level Multilevel 


Message ID Stripping 


X X 


Text Insertion 


X X 


Formatting Only 


X 


Second Level Informational Chaining 


X 



Figure 12-26. PUTLINE Functions and Message Types 

Stripping Message Identifiers: The user indicates whether or not he wants 
message identifiers displayed at the terminal. The use does this with the 
PROFILE command. (See TSO/E Command Language Reference and TSO/E 
User's Guide.) If the terminal user indicates no message identifiers are to be 
displayed, the PUTLINE service routine strips them off the message before 
writing the message to the terminal. 

A message identifier must be a variable-length character string, containing no 
leading or embedded blanks, must not exceed a maximum length of 255 
characters, and must be terminated by a blank. 

Messages without message identifiers must begin with a blank. A message 
beginning with a blank is handled by the PUTLINE service routine as a message 
that does not require message identifier stripping, regardless of what the user at 
the terminal has requested. If you do not provide a message identifier, and do 
not begin your message with a blank, the beginning of your message up to the 
first blank will be stripped off by the PUTLINE service routine if message 
identifier stripping is requested from the terminal. If the message segment does 
not contain at least one blank, PUTLINE will return a code of 12 (invalid 
parameters) in register 15, even if message ID stripping is not requested from the 
terminal. 

The following examples show the effects of the PUTLINE message identifier 
stripping function. 

If you provide message identifiers on your messages and the terminal user does 
not request message ID stripping, your message will appear at the terminal exactly 
as it appears here: 

MESSAGE0010 THIS IS A MESSAGE. 
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If the user at the terminal requests message ID stripping, the message will appear 
as: 

THIS IS A MESSAGE. 

If you do not want to use message identifiers on your output messages, begin your 
message with a blank. A message beginning with a blank is unaffected by a 
terminal user's request for message ID stripping and will appear as you wrote it, 
minus the blank. 

Using the PUTLINE Text Insertion Function: The text insertion function of the 
PUTLINE service routine allows you to build or modify messages at the time you 
put them out to the terminal. With text insertion you can respond to different 
output message requirements with one basic message (the primary segment). You 
can insert text into this primary segment or add text to it, and thereby build an 
output message to meet the current processing situation. 

To use text insertion you pass your messages to the PUTLINE service routine as 
a variable number of text segments - from 1 to 255 segments are permissible. 
Each segment may contain from to 255 characters, however, the total number of 
characters in all the segments must not exceed 256. You must precede each of 
these text segments with a four-byte header: the first two bytes containing the 
length of the message, including the header, and the second two bytes containing 
an offset value. The offset value in the primary segment must be zero. The offset 
in any secondary segments may be from zero to the length of the primary 
segment's text field. An offset of zero in a secondary segment implies that the 
segment is to be placed before the primary segment. An offset that is equal to the 
length of the primary segment's text field implies that the secondary segment is to 
be placed after the primary segment. An offset of n, where n represents a value 
greater than zero but less than the total length of the primary segment, implies 
that the segment is to be inserted after the nth byte of the primary segment. 
PUTLINE places the secondary segment after that character, completes the 
message, and puts it out to the terminal. 

If you specify an offset in a secondary segment, greater than the length of the 
primary segment, PUTLINE cannot handle the request and returns an error code 
of 12 (invalid parameters) in register 15. If the secondary segments do not appear 
in the OLD with their offsets in ascending order, PUTLINE returns an error code 
of 12 (invalid parameters) in register 15. 

If you provide more than one secondary segment to be inserted into a primary 
segment, the offset fields on each of the secondary segments must indicate the 
position within the original primary segment at which you want them to appear. 
PUTLINE determines the points of insertion by counting the characters of the 
original primary segment only. As an example, if you provided one primary and 
two secondary segments as shown: 



2 bytes 


2 bytes 




28 bytes 


32 





PLEASE ENTER TO PROCESSING 



9 


14 


TEXT 



13 


17 


CONTINUE 
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PUTLINE would place the first insert, TEXT, after the 1 3th character, and the 
second insert, CONTINUE, after the 17th character of the text field of the 
primary segment. After PUTLINE inserts the two text segments, the message 
would read: 

PLEASE ENTER TEXT TO CONTINUE PROCESSING 

The leading and trailing blanks are automatically stripped off before the message 
is written to the terminal. 

Figure 12-27 is an example of the code required to make use of the text insertion 
feature of the PUTLINE service routine; it uses the text segments shown above. 

Note that the operand INFOR, which indicates to the PUTLINE service routine 
that the text segments are to be processed as informational messages, requires an 
output line descriptor to point to the message segments. Only one output line 
descriptor (ONEOLD) is required to point to the 3 message segments because the 
3 segments are to be combined into one single level message. 
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Figure 12-27 (Part 1 of 2). Coding Example - PUTLINE Text Insertion 
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Figure 12-27 (Part 2 of 2). Coding Example - PUTLINE Text Insertion 



Using the Format Only Function: You can also use the PUTLINE service routine 
to format a message but not write it at the terminal. To do this, code the 
FORMAT operand in the PUTLINE macro instruction and pass PUTLINE the 
same message segment structure required for the text insertion function. The 
PUTLINE service routine performs text insertion if requested and places the 
finished message in subpool 1, which is not shared. It then places the address of 
the formatted line into the third word of the PUTLINE parameter block. The 
storage occupied by the formatted message belongs to your program and, if space 
is a consideration, must be freed by it. The returned formatted line is in the 
variable-length record format; that is, it is preceded by a four-byte header. You 
can use the first two bytes of this header to determine the length of the returned 
message, and later, to free the real storage occupied by the message with the R 
form of the FREEMAIN macro instruction. 

One difference between format only processing and text insertion processing is 
that format only processing can be used only on single level messages. You 
cannot use the format only feature to format multilevel messages. You can 
however, use the second level informational chaining function of PUTLINE to 
format second level messages and place them on an internal chain. 
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Building a Second Level Informational Chain: PUTLINE can accept two levels of 
informational messages at each execution of the service routine. It formats the 
first level message and puts it out to the terminal. The second level message is 
formatted and a copy of it is placed on an internal chain in shared subpool 78. 
This internal chain, the second level informational chain, is maintained by the I/O 
service routines for the duration of one command or subcommand processor. 
You can use the PUTLINE service routine to purge this chain or to put it out to 
the terminal in its entirety. 

To purge the chain without putting it out to the terminal, you must turn on the 
high order bit in the first byte (ECTMSGF) of the third word of the environment 
control table (ECT). The ECT is pointed to by the second word of the 
input/output parameter list, and may be mapped by the IKJECT DSECT. The 
next time any chaining or unchaining is requested with PUTLINE or PUTGET, 
the second level informational chain will be eliminated. 

To put the entire chain out to the terminal, use the PUTLINE macro instruction 
and place a zero address where the output line address is normally required. This 
will cause the PUTLINE service routine to write the chain to the terminal and 
eliminate the internal chain. You will normally use this procedure only if your 
attention exit routine is using the PUTLINE macro instruction to process a 
question mark entered from the terminal. 

Figure 12-28 is an example of the code required to build a second level 
informational chain. It executes the PUTLINE service routine by using two 
different execute form macro instructions to modify the PUTLINE parameter 
block built by the list form of the PUTLINE macro instruction. 

The code shown puts two messages out to the terminal and places two second 
level messages on an internal chain. It then executes a third execute form of the 
PUTLINE macro instruction with a zero OUTPUT address to put the second 
level chain out to the terminal. 

Note that the offset value for the primary message segment must always be zero, 
and when placing second level messages on an internal chain, the offset value for 
the second level message must also be zero. Note also that you do not place a 
message identifier on a second level message. 
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Figure 12-28 (Part 1 of 2). Coding Example - PUTLINE Second Level Informational Chaining 
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Figure 12-28 (Part 2 of 2). Coding Example - PUTLINE Second Level Informational Chaining 
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Return Codes from PUTLINE 

When the PUTLINE service routine returns control to the program that invoked 
it, it provides one of the following return codes in general register 15: 

Code Meaning 

decimal 

PUTLINE completed normally. 

4 The PUTLINE service routine did not complete. An attention interruption occurred during 

its execution, and the attention handler turned on the completion bit in the communications 
ECB. 

8 The NO WAIT option was specified and the line was not written to the terminal. 

12 Invalid parameters were supplied to the PUTLINE service routine. 

16 A conditional GETMAIN was issued by PUTLINE for output buffers and there was not 

sufficient real storage to satisfy the request. 

20 The terminal has been disconnected. 

Note: The GNRLFAIL service routine described in this book can be invoked to 
issue a meaningful error message for a PUTLINE error code. 

PUTGET - Putting a Message Out to the Terminal and Obtaining a Line of Input in 
Response 

Use the PUTGET macro instruction to put messages out to the terminal and to 
obtain a response to those messages. A message to the user at the terminal which 
requires a response is called a conversational message. There are two types of 
conversational messages: 

# Mode messages - Those which tell the user at the terminal which processing 
mode he is in so that he can enter a response applicable to that processing 
mode. Examples of mode messages are the READY message sent to the 
terminal by the terminal monitor program to indicate that it expects a 
command to be entered, and the command name (EDIT, TEST, etc.) sent by 
a command processor to indicate that it is ready to accept a subcommand, 
name. 

• Prompt messages - Those which prompt the user at the terminal to enter 
parameters required by the program in control, or to reenter those parameters 
which were previously entered incorrectly. Prompt information can only be 
obtained from the user at the terminal. 

The input line returned by the PUTGET service routine can come from the 
terminal or from an in-storage list; PUTGET determines the source of input from 
the top element of the input stack unless you have specified the TERM or ATTN 
operands in the PUTGET macro instruction. 

PUTGET, like PUTLINE and GETLINE, has many parameters. The parameters 
are passed to the PUTGET service routine according to the operands you code in 
the list and the execute forms of the PUTGET macro instruction. 
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This topic describes: 

• The list and execute forms of the PUTGET macro instruction 

• Building the PUTGET parameter block 

• Types and formats of the output line 

• Passing the message lines to PUTGET 

• PUTGET processing 

• Input line format - the input buffer 

• An example of PUTGET 

• Return codes from PUTGET 



The PUTGET Macro Instruction - List Form 



The list form of the PUTGET macro instruction builds and initializes a PUTGET 
parameter block (PGPB), according to the operands you specify in the PUTGET 
macro instruction. The PUTGET parameter block indicates to the PUTGET 
service routine which of the PUTGET functions you want performed. 
Figure 12-29 shows the list form of the PUTGET macro instruction; each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



[symbol] 



PUTGET 



OUTPUT=( output address 



t 



SINGLE ) 
MULTLVLI< 



/, PROMPT '1 
,MODE 
,PTBYPS 
,TERM 
,ATTN 



,TERMPUT=( 



EDIT 
ASIS 
CONTROL 



{: 



WAIT 



", TERMGET= (J EDIT ) /, WAIT 1)1, MF=L 
|ASISJ |,NOWAITJ J 



K. NOHOLP ) ( , NOBREAK ) ) 
,HOLD J|,BREAKINJ 



Figure 12-29. The List Form of the PUTGET Macro Instruction 



OUTPUT = output address 

Specify the address of the output line descriptor or a zero. The output line 
descriptor (OLD) describes the message to be put out, and contains the 
address of the beginning (the one-word header) of the message or messages 
to be written to the terminal. You have the option under MODE 
processing to provide or not provide an output message. If you do not 
provide an output line, code OUTPUT = 0, and only the GET functions will 
take place. If you do provide an output message, the type of message and 
the processing to be performed by the PUTGET service routine are 
described by the OUTPUT sublist operands SINGLE, MULTLVL, 
PROMPT, MODE, PTBYPS, TERM, and ATTN. SINGLE and 
PROMPT are the default values. 

SINGLE 

The output message is a single level message. 
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MULTLVL 

The output message consists of multiple levels. The first level message is 
written to the terminal, the second level messages are printed at the 
terminal, one at a time, in response to question marks entered from the 
terminal. PROMPT must also be specified or defaulted to. 

PROMPT 

The output line is a prompt message. 

MODE 

The output line is a mode message. 

PTBYPS 

The output line is a prompt message and the terminal user's response will 
not be displayed at those terminals that support the print inhibit feature. A 
terminal user can override bypass processing by pressing an attention 
followed by pressing the ENTER key before entering input. 

TERM 

Specifies that the output line (a mode message) is to be written to the 
terminal, and a line is to be returned from the terminal, regardless of the 
top element of the input stack. 

ATTN 

Specifies that the output line (a mode message) is to be initially suppressed 
but an input line is to be returned from the terminal. 

TERMPUT = 

Specifies the TPUT options requested. Since PUTGET issues a TPUT SVC 
to write the message to the terminal, this operand is used to indicate which 
of the TPUT options you want to use. The TPUT options are EDIT, ASIS 
or CONTROL; WAIT, or NOWAIT; NOHOLD, or HOLD; and 
NOBREAK or BREAKIN. The default values are EDIT, WAIT, 
NOHOLD, and NOBREAK. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the following TPUT 
functions are requested: 

1 . Any trailing blanks are removed before the line is written to the 
terminal. If a blank line is sent, the terminal vertically spaces one line. 

2. Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 

3. All terminal control characters (for example: bypass, restore, horizontal 
tab, new line) are replaced with a printable character. Backspace is an 
exception; see item 4 under ASIS. 
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ASIS 

Specifies that minimal editing is to be performed by TPUT as follows: 

1 . The line of output is to be translated from EBCDIC to terminal code. 
Invalid characters will be converted to printable characters to prevent 
program caused I/O errors. This does not mean that all unprintable 
characters will be eliminated. Restore, upper case, lower case, bypass, 
and bell ring, for example, might be valid but nonprinting characters at 
some terminals. (See CONTROL.) 

2. Transmission control characters will be added. 

3. EBCDIC NL, placed at the end of the message, indicates to the TPUT 
SVC that the cursor is to be returned at the end of the line. NL is 
replaced with whatever is necessary for that particular terminal type to 
cause the cursor to return. This NL processing occurs only if you 
specify ASIS, and the NL is the last character in your message. 

If you specify EDIT, NL is handled as described in item 3 under EDIT. 

If the NL is embedded in your message, it is sent to the terminal as a 
cursor return. No idle characters are added (see item 6 below). This 
may cause overprinting, particularly on terminals that require a line-feed 
character to position the cursor on a new line. 

4. If you have used backspace in your output message but the backspace 
character does not exist on the terminal type to which the message is 
being routed, TPUT attempts alternate methods to accomplish the 
backspace. 

5. Control characters are added as needed to cause the message to occur 
on several lines if the output line is longer than the terminal line size. 

6. Idle characters are sent at the end of each line to prevent typing as the 
carrier returns. 

No line continuation checking is done. 

CONTROL 

Specifies that the output line is composed of terminal control characters and 
will not display or move the cursor on the terminal. This option should be 
used for transmission of characters such as bypass, restore, or bell ring. See 
ASIS for additional information. 

WAIT 

Specifies that control will not be returned to the program that issued the 
PUTGET until the output line has been placed into a terminal output 
buffer. 

NOWAIT 

Specifies that control should be returned to the program that issued the 
PUTGET macro instruction, whether or not a terminal output buffer is 
available. If no buffer is available a return code of 16 (decimal) is returned. 
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NOHOLD 

Specifies that control is to be returned to the issuer of the PUTGET macro 
instruction, and that program can resume processing as soon as the output 
line has been placed on the output queue. 

HOLD 

Specifies that the program that issued the PUTGET macro instruction 
cannot continue its processing until this output line has been put out to the 
terminal or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, he is not to be 
interrupted. The output message is placed on the output queue to be 
displayed after the terminal user has completed the line. 

BREAKIN 

Specifies that output has precedence over input. If the user at the terminal 
is transmitting, he is interrupted, and this output line is sent. Any data that 
was received before the interruption is kept and displayed at the terminal 
following this output line. 

TERMGET = 

Specifies the TGET options requested. Since PUTGET issues a TGET SVC 
to bring in a line of data, this operand is used to indicate to the TGET SVC 
which of the TGET options you wish to use. The TGET options are EDIT 
or ASIS, and WAIT or NO WAIT. The default values are EDIT and 
WAIT. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the buffer is to be 
filled out with trailing blanks. 

ASIS 

Specifies that minimal editing is to be done as follows: 

1 . Transmission control characters are removed. 

2. The line of input is translated from terminal code to EBCDIC. 

3. Line deletion and character deletion editing is performed. 

4. Line feed and cursor return characters, if present, are removed. 

No line continuation checking is done. 

WAIT 

Specifies that control is to be returned to the program that issued the 
PUTGET macro instruction, only after an input message has been read. 

NOWAIT 

Specifies that control should be returned to the program that issued the 
PUTGET macro instruction whether or not a line of input is available. If a 
line of input is not available, a return code of 20 (decimal) is returned in 
register 15 to the command processor. 
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MF = L 

Indicates that this is the list form of the macro instruction. 

Note: In the list form of the PUTGET macro instruction, only 



PUTGET mf=l 



is required. 

The output line address is not specifically required in the list form of the 
PUTGET macro instruction, but must be coded in either the list or the execute 
form. 

The other operands and their sublists are optional because you can supply them in 
the execute form of the macro instruction, or if you want the default values, they 
are supplied automatically by the expansion of the macro instruction. 

The operands you specify in the list form of the PUTGET macro instruction set 
up control information used by the PUTGET service routine. This control 
information is passed to the PUTGET service routine in the PUTGET parameter 
block, a four-word parameter block built and initialized by the list form of the 
PUTGET macro instruction. 



The PUTGET Macro Instruction - Execute Form 



Use the execute form of the PUTGET macro instruction to prepare a mode or a 
prompt message for output to the terminal, to determine whether or not that 
message should be sent to the terminal, and to return a line of input from the 
source indicated by the top element of the input stack to the program that issued 
the PUTGET macro instruction. 

You can use the execute form of the PUTGET macro instruction to build and 
initialize the input/output parameter list required by the PUTGET service routine, 
and to request PUTGET functions not already requested by the list form of the 
macro instruction, or to change those functions previously requested in either a 
list form or a previous execute form of the PUTGET macro instruction. 
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Figure 12-30 shows the execute form of the PUTGET macro instruction; each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



[symbol] 



PUTGET 



[PARM=parameter address] [ ,UPT=upt address) 

,ECT=ect address] [ ,ECB=ecb address] 

/ , PROMPT 1 
,OUTPUT=( output address j, SINGLE ) 

MULTLVLK 



fc 



,MODE 
,PTBYPS 
,TERM 
V,ATTN / 



EDIT 



,TERMPUT=( ASIS f, WAIT ) ( , NOHOLD ) /, NOBRE AK \ ) 

(CONTROL) |,N0WAITJ |,HOLD f (,BREAKINJ 

",TERMGET=C (EDIT W, WAII \)1 
| ASIS j \,NOWAITJ J 

,ENTRY= /entry address) 1 ,MF=(E/list address)) 

\ (15) f] \ (1) / 



Figure 12-30. The Execute Form of the PUTGET Macro Instruction 



P ARM = parameter address 

Specifies the address of the four-word PUTGET parameter block (PGPB). 
This address is placed into the input/output parameter list (IOPL). It may 
be the address of a list form PUTGET macro instruction. The address is 
any address valid in an RX instruction, or you can put it in one of the 
general registers 2-12, and use that register number, enclosed in parentheses, 
as the parameter address. 

UPT = upt address 

Specifies the address of the user profile table (UPT). This address is placed 
into the IOPL when the execute form of the PUTGET macro instruction 
expands. You can obtain this address from the command processor 
parameter list (CPPL) pointed to by register 1 when the command processor 
is attached by the terminal monitor program. The address can be used as 
received in the CPPL or you can put it in one of the general registers 2-12, 
and use that register number, enclosed in parentheses, as the UPT address. 

ECT = ect address 

Specifies the address of the environment control table (ECT). This address 
is placed into the IOPL when the execute form of the PUTGET macro 
instruction expands. You can obtain this address from the command 
processor parameter list (CPPL) pointed to by register one when the 
command processor is attached by the terminal monitor program. The 
address can be used as received in the CPPL or you can put it in one of the 
general registers 2-12, and use that register number, enclosed in parentheses, 
as the ECT address. 

ECB = ecb address 

Specifies the address of the command processor event control block (ECB). 
This address is placed into the IOPL by the execute form of the PUTGET 
macro instruction when it expands. 
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You must provide a one-word event control block and pass its address to 
the PUTGET service routine by placing the address into the IOPL. If you 
code the address of the ECB in the execute form of the PUTGET macro 
instruction, the macro instruction places the address into the IOPL for you. 
The address can be any address valid in an RX instruction, or you can put 
it in one of the general registers 2-12, and use that register number, enclosed 
in parentheses, as the ECB address. 

OUTPUT = output address 

Specifies the address of the output line descriptor or a zero. The output line 
descriptor (OLD) describes the message to be put out, and contains the 
address of the beginning (the one-word header) of the message or messages 
to be written to the terminal. You have the option under MODE 
processing to provide or not provide an output message. If you do not 
provide an output line, code OUTPUT = 0, and only the GET function will 
take place. If you do provide an output message, the type of message and 
the processing to be performed by the PUTGET service routine are 
described by the OUTPUT sublist operands SINGLE, MULTLVL, 
PROMPT, MODE, PTBYPS, TERM, and ATTN. The default values are 
SINGLE and PROMPT. 

SINGLE 

The output message is a single level message. 

MULTLVL 

The output message consists of multiple levels. The first level message is 
written to the terminal, the second level messages are displayed at the 
terminal, one at a time, in response to question marks entered from the 
terminal. PROMPT must also be specified or defaulted to. 

PROMPT 

The output line is a prompt message. 

MODE 

The output line is a mode message. 

PTBYPS 

The output line is a prompt message and the terminal user's response will 
not display at those terminals that support the print inhibit feature. A 
terminal user can override bypass processing by pressing an attention 
followed by pressing the ENTER key before entering input. 

TERM 

Specifies that the output line (a mode message) is to be written to the 
terminal, and a line is to be returned from the terminal, regardless of the 
top element of the input stack. 

ATTN 

Specifies that the output line (a mode message) is to be initially suppressed 
but an input line is to be returned from the terminal. 
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TERMPUT = 

Specifies the TPUT options requested. PUTGET issues a TPUT SVC to 
write the message to the terminal. This operand is used to indicate which of 
the TPUT options you want to use. The TPUT options are EDIT, ASIS or 
CONTROL; WAIT or NOW AIT; NOHOLD or HOLD; and NOBREAK 
or BREAKIN. The default values are EDIT, WAIT, NOHOLD and 
NOBREAK. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the following TPUT 
functions are requested: 

1 . Any trailing blanks are removed before the line is written to the 
terminal. If a blank line is sent, the terminal vertically spaces one line. 

2. Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 

3. All terminal control characters (for example: bypass, restore, horizontal 
tab, new line) are replaced with a printable character. Backspace is an 
exception; see item 4 under ASIS. 

ASIS 

Specifies that minimal editing is to be performed by TPUT as follows: 

1 . The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to prevent 
program caused I/O errors. This does not mean that all unprintable 
characters will be eliminated. Restore, upper case, lower case, bypass, 
and bell ring, for example, might be valid but nonprinting characters at 
some terminals. (See CONTROL.) 

2. Transmission control characters are added. 

3. EBCDIC NL, placed at the end of the message, indicates to the TPUT 
SVC that the cursor is to be returned at the end of the line. NL is 
replaced with whatever is necessary for that particular terminal type to 
cause the cursor to return. This NL processing occurs only if you 
specify ASIS, and the NL is the last character in your message. 

If you specify EDIT, NL is handled as described in item 3 under EDIT. 

If the NL is embedded in your message, it is sent to the terminal as a 
cursor return. No idle characters are added (see item 6 below). This 
may cause overprinting, particularly on terminals that require a line-feed 
character to position the cursor on a new line. 

4. If you have used backspace in your output message, but the backspace 
character does not exist on the terminal type to which the message is 
being routed, TPUT attempts alternate methods to accomplish the 
backspace. 

5. Control characters are added as needed to cause the message to occur 
on several lines if the output line is longer than the terminal line size. 
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6. Idle characters are sent at the end of each line to prevent typing as the 
cursor returns. 

No line continuation checking is done. 

CONTROL 

Specifies that this line is composed of terminal control characters and will 
not display or move the cursor on the terminal. This option should be used 
for transmission of characters such as bypass, restore, or bell ring. 

WAIT 

Specifies that control will not be returned to the program that issued the 
PUTGET until the output line has been placed into the terminal output 
buffer. 

NOWAIT 

Specifies that control should be returned to the program that issued the 
PUTGET macro instruction, whether or not a terminal output buffer is 
available. If no buffer is available, a return code of 16 (decimal) is returned. 

NOHOLD 

Specifies that control is to be returned to the program that issued the 
PUTGET macro instruction, and it can continue processing as soon as the 
output line has been placed on the output queue. 

HOLD 

Specifies that the program that issued the PUTGET macro instruction 
cannot continue its processing until the output line has been put out to the 
terminal or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, he is not to be 
interrupted. The output message is placed on the output queue to be 
displayed after the terminal user has completed the line. 

BREAKIN 

Specifies that output has precedence over input. If the user at the terminal 
is transmitting, he is interrupted, and this output line is sent. Any data that 
was received before the interruption is kept and displayed at the terminal 
following this output line. 

TERMGET = 

Specifies the TGET options requested. PUTGET issues a TGET SVC to 
bring in a line of data. This operand is used to indicate to the TGET SVC 
which of the TGET options you want to use. The TGET options are EDIT 
or ASIS, and WAIT or NOWAIT. The default values are EDIT and 
WAIT. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the buffer is filled 
out with trailing blanks. 
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ASIS 

Specifies that minimal editing is done as follows: 

1 . Transmission control characters are removed. 

2. The line of input is translated from terminal code to EBCDIC. 

3. Line deletion and character deletion editing is performed. 

4. Line feed and cursor return characters, if present, are removed. 

No line continuation checking is done. 

WAIT 

Specifies that control is to be returned to the program that issued the 
PUTGET macro instruction, only when an input message has been read. 

NOWAIT 

Specifies that control should be returned to the program that issued the 
PUTGET macro instruction whether or not a line of input is available. If a 
line of input is not available, a return code of 20 (decimal) is returned in 
register 15. 

ENTRY = entry point address 

(15) 
Specifies the entry point of the PUTGET service routine. If ENTRY is 
omitted, the PUTGET macro expansion generates a LINK macro 
instruction to invoke the PUTGET service routine. The address may be any 
address valid in an RX instruction or (15) if you load the entry point 
address into general register 15. 

MF = E 

Indicates that this is the execute form of the PUTGET macro instruction. 

listaddr 

(1) 

The address of the four-word input/output parameter list (IOPL). This can 
be a completed IOPL that you have built, or it may be 4 words of declared 
storage that will be filled from the PARM, UPT, ECT, and ECB operands 
of this execute form of the PUTGET macro instruction. The address must 
be any address valid in an RX instruction or (1) if you have loaded the 
parameter list address into general register 1 . 

Note: In the execute form of the PUTGET macro instruction, only the following 
is required: 



PUTGET 



MF=(E 



,/list address)) 

1 (i) ) 



The PARM, UPT, ECT, and ECB operands are not required if you have built 
your IOPL in your own code. 

The output line address is not specifically required in the execute form of the 
PUTGET macro instruction, but must be coded in either the list or the execute 
form. 
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The other operands and sublists are optional because you may have supplied them 
in the list form of the macro instruction or in a previous execute form, or because 
you may want to use the default values which are automatically supplied by the 
macro expansion itself. 

The ENTRY operand need not be coded in the macro instruction. If it is not, a 
LINK macro instruction is generated by the PUTGET macro expansion to invoke 
the PUTGET service routine. 

The operands you specify in the execute form of the PUTGET macro instruction 
set up control information used by the PUTGET service routine. You can use the 
PARM, UPT, ECT, and ECB operands of the PUTGET macro instruction to 
build, complete, or modify an IOPL. The OUTPUT, TERMPUT, and 
TERMGET operands and their sublist operands initialize the PUTGET 
parameter block. The PUTGET parameter block is referenced by the PUTGET 
service routine to determine which functions you want PUTGET to perform. 



Building the PUTGET Parameter Block (PGPB) 



When the list form of the PUTGET macro instruction expands, it builds a 
four-word PUTGET parameter block (PGPB). This PGPB combines the 
functions of the PUTLINE and the GETLINE parameter blocks and contains 
information used by the PUT and the GET functions of the PUTGET service 
routine. The list form of the PUTGET macro instruction initializes this PGPB 
according to the operands you have coded in the macro instruction. This 
initialized block, which you may later modify with the execute form of the 
PUTGET macro instruction, indicates to the PUTGET service routine the 
functions you want performed. It also contains a pointer to the output line 
descriptor that describes the output message and it provides a field into which the 
PUTGET service routine places the address of the input line returned from the 
input source. 

You must pass the address of the PGPB to the execute form of the PUTGET 
macro instruction. Since the list form of the macro instruction expands into a 
PGPB, all you need do is pass the address of the list form of the macro 
instruction to the execute form as the PARM value. 
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The PUTGET parameter block is defined by the IKJPGPB DSECT. 
Figure 12-31 describes the contents of the PUTGET parameter block. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 




PUT control flags. These bits describe the output line to the PUTGET 
service routine. 




Bytel 

..0 

...1 .... 
.... 0... 

1.. 

1 

XX.. ..X. 


Always zero for PUTGET. 

The output line is a single level message. 

Must be zero for PUTGET. 

The output line is a multilevel message. 

The output line is a PROMPT message. 

Reserved. 




Byte 2 

1 

...1 .... 
.... 1... 

.XX. .XXX 


The output line is a MODE message. 
BYPASS processing is requested. 
ATTN processing is requested. 
Reserved. 


2 




TPUT options field. These bits indicate to the TPUT SVC which of the 
TPUT options you want to use. 




Byte 1 



Always set to for TPUT. 




...0 .... 


WAIT processing has been requested. Control will be returned to the 
issuer of TPUT only after the output line has been placed into a 
terminal output buffer. 




...1 .... 


NOWAIT processing has been requested. Control will be returned to 
the issuer of TPUT whether or not a terminal output buffer is available. 




.... 0... 


NOHOLD processing has been requested. The issuer of the TPUT can 
resume processing as soon as the output line has been placed on the 
output queue. 




.... 1... 


HOLD processing has been requested. The issuer of the TPUT is not to 
resume processing until the output line has been written to the terminal 
or deleted. 




0.. 


NOBREAK processing has been requested. The output line will be 
displayed only when the terminal user is not entering a line. 




1.. 


BREAKIN processing has been requested. The output line is to be sent 
to the terminal immediately. If the terminal user is entering a line, he is 
to be interrupted. 




00 


EDIT processing has been requested. 




01 


ASIS processing has been requested. 




10 


CONTROL processing has been requested. 




.XX 


Reserved. 




Byte 2 


Reserved. 


4 




The address of the output line descriptor. 


2 




GET control flags. 




Byte 1 

.00 

...1 .... 

X... XXXX 


Always zero for PUTGET. 
TERM processing is requested. 
Reserved bits. 




Byte 2 
XXXX xxxx 


Reserved. 



Figure 12-31 (Part 1 of 2). The PUTGET Parameter Block 
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Number 
of Bytes 


Field 


Contents or Meaning 


2 




TGET options field. These bits indicate to the TGET SVC which of the 
TGET options you wish to use. 




Byte 1 
1 


Always set to 1 for TGET. 




...0 .... 
...1 .... 


WAIT processing has been requested. Control will be returned to the 
issuer of the TGET SVC only after an input message has been read. 

NOWAIT processing has been requested. Control will be returned to 
the issuer of the TGET SVC whether or not a line of input is available. 
If no line was available, PUTGET returns a code of 20 (decimal) in 
general register 15. 




00 


EDIT processing has been requested. In addition to the editing 
provided by ASIS processing, the input buffer is to be filled out with 
trailing blanks to the next doubleword boundary. 




01 


ASIS processing has been requested. (See the ASIS operand of the 
PUTGET macro instruction description.) 




.XX. XX.. 


Reserved bits. 




Byte 2 

XXXX XXXX 


Reserved. 


4 


PGPBIBUF 


The address of the input buffer. The PUTGET service routine fills this 
field with the address of the input buffer in which the input line has 
been placed. 



Figure 12-31 (Part 2 of 2). The PUTGET Parameter Block 



Types and Formats of the Output Line 



The PUTGET service routine writes only conversational messages to the terminal, 
it does not handle data lines. For information on how to write a data line or a 
nonconversational message to the terminal, see the section on the PUTLINE 
macro instruction. 

PUTGET accepts two output line formats depending upon whether the message 
you provide is a single level message or a multilevel message. 

Single Level Messages: A single level message is composed of one or more 
message segments to be formatted and written to the terminal with one execution 
of the PUTGET macro instruction. 

Multilevel Messages: A multilevel message is composed of one or more segments 
to be formatted and written to the terminal, and one or more message segments to 
be formatted and written to the terminal in response to question marks entered 
from the terminal. Note, however, that if you specify MODE in the PUTGET 
macro instruction, you can process only single level messages. If you specify 
PROMPT and TERMGET = EDIT in the PUTGET macro instruction, then 
second level messages will be written to the terminal, one at a time, in response to 
successive question marks entered from the terminal. If PROMPT messages are 
to be available to the user at the terminal, however, the top element of the input 
stack must not specify a procedure element as the current source of input, and the 
terminal user must not have inhibited prompting. (See the PROFILE command 
in TSO/E Command Language Reference.) 
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Passing the Message Lines to PUTGET 



You must build each of the message segments to be processed by the PUTGET 
service routine as if it were a line of single line data. The segment must be 
preceded by a four-byte header field - the first two bytes containing the length of 
the segment including the header, and the second two bytes containing zeros or an 
offset value if you use the text insertion facility provided by PUTGET. This 
message line format is required whether the message is a single level message or a 
multilevel message. 

Because of the additional functions performed on message lines - message ID 
stripping, text insertion, and multilevel processing - you must provide the 
PUTGET service routine with a description of the line or lines that are to be 
processed. This is done with an output line descriptor (OLD). 

There are two types of output line descriptors. The type depends on whether the 
messages are single level or multilevel. 

The OLD required for a single level message is a variable length control block 
which begins with a fullword value representing the number of segments in the 
message, followed by fullword pointers to each of the segments. 

The format of the OLD for multilevel messages varies from that required for 
single level messages in only one respect. You must preface the OLD with a 
fullword forward-chain pointer. This chain pointer points to another output line 
descriptor or contains zero to indicate that it is the last OLD on the chain. 
Figure 12-32 shows the format of the output line descriptor. 



Number 
of Bytes 


Field 


Contents or Meaning 


4 

4 
4 
4 
4 




The address of the next OLD, or zero if this is the last one on the chain. 
This field is present only if the message pointed to is a multilevel 
message. 

The number of message segments pointed to by this OLD. 

The address of the first message segment. 

The address of the next message segment. 

The address of the nth message segment. 



Figure 12-32. The Output Line Descriptor (OLD) 

You must build the output line descriptor and pass its address to the PUTLINE 
service routine as the OUTPUT operand address in either the list or the execute 
form of the macro instruction. When the macro instruction expands, it places this 
OLD address into the second word of the PUTLINE parameter block. 

Figure 12-33 shows the two control block structures possible when passing an 
output message to the PUTGET service routine. Note that MODE, TERM, or 
ATTN may not be coded in the PUTGET macro instruction if you want to 
provide multilevel messages to the terminal. (Mode messages can have only one 
level.) 

Message segments for PUTGET must follow the same rules as those for 
PUTLINE informational processing. (See the section on "Stripping Message 
Identifiers.") Note that if a PUTGET message segment does not contain at least 
one blank, a return code of 24 (invalid parameters) will be received in register 15. 
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Figure 12-33. Control Block Structures for PUTGET Output Messages 
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PUTGET Processing 



Text insertion and message identifier stripping are available to all output messages 
processed by the PUTGET service routine. For a detailed description of these 
functions see "PUTLINE Message Line Processing." 

The PUTGET service routine provides other processing capabilities dependent 
upon whether the message is a mode or a prompt message. 

Mode Message Processing: A mode message is a message put out to the terminal 
when a command or a subcommand is anticipated. The processing of mode 
messages by the PUTGET service routine is dependent upon the following two 
conditions: 

1. Are you providing an output line? 

2. From what source is the input line coming? 

Is an Output Line Present: You need not provide an output line to the PUTGET 

service routine. If you do provide an output line address then PUT processing 
will take place. Whether your output line is written to the terminal is then 
dependent upon the input source indicated by the input stack. If you do not 
provide an output line (OUTPUT = 0) then only the GET function of the 
PUTGET service routine takes place. 

What is the Input Source: The source of the input line, as determined by the top 
element of the input stack, determines the type of processing performed by the 
PUTGET service routine. You can override the input stack by coding the TERM 
or ATTN operands in the PUTGET macro instruction. The two sources of input 
supported are: 

1 . Terminal 

2. In-storage 

If the current source of input is the terminal, and you provide an output line, the 
PUTGET service routine writes the line to the terminal, returns a line from the 
terminal, and places the address of the returned line into the fourth word of the 
PUTGET parameter block. If the line returned from the terminal is a question 
mark, however, the PUTGET service routine causes the second level message (if 
one exists) to be written to the terminal, again puts out the mode message, and 
then returns a line from the terminal. If the user at the terminal enters a question 
mark in response to a mode message, and no second level message exists, 
PUTGET puts out the message "IKJ66760I NO INFORMATION 
AVAILABLE," puts the mode message out again, and returns a line from the 
terminal. 

Note that if the user enters a question mark from the terminal, the second level 
message returned to the terminal is not related to the current mode message but 
to the command processor just terminated; mode messages can have only one 
level. 

If the current source of input is an in-storage list, the output line (if you provide 
one) is ignored and the PUTGET service routine normally obtains an input line 
from the in-storage list and places a pointer to that line in the fourth word of the 
PGPB. If however, a second level message exists, PUTGET will only return a 
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line if the user at the terminal has access to the information in the chain through 
the PAUSE mechanism. If the chain is not available to the user, no line is 
obtained by PUTGET, and it returns a code of 12 in register 15. You can test 
this return code, and if you want, recover from this error condition by turning on 
the high order bit of the ECTMSGF field of the environment control table and 
reissuing the PUTGET. The second level message is then purged and a line is 
obtained from the in-storage list. 

Pause Processing: If the terminal user has requested the PAUSE option on the 
PROFILE command, the PUTGET service routine makes the second level 
messages available to him, even if the current input source is not the terminal. 

PAUSE processing works as follows. If a second level message does exist, 
PUTGET puts out the message "IKJ56762A PAUSE" to the terminal informing 
the terminal user that PAUSE processing is in effect. At this point the terminal 
user can enter either a question mark to indicate that he wishes to have the 
second level messages put out to the terminal, or press the ENTER key to 
indicate that the information is not needed. If the user presses the ENTER key, 
the second level message is eliminated. If he enters any response other than a 
question mark or hitting the ENTER key, PUTGET prompts him for a correct 
response. 

Prompt Message Processing: A prompt message is a message put out to the 
terminal when the program in control requires input from the terminal user. 
PROMPT information must come from the terminal and can not be obtained 
from any other source of input. There are three cases when a request for 
PROMPT processing is denied by PUTGET: 

• When the current source of input, as determined by the top element of the 
input stack, is an in-storage procedure that is not an EXEC command 
procedure. 

• When the NOPROMPT attribute is specified in the user's profile table (UPT). 

• When an EXEC command procedure, executing in the background, does not 
have a DATA PROMPT entry to satisfy the request or a PROMPT control 
statement. 

When the PUTGET service routine returns control to the program that invoked 
it, it returns a return code of 12 when no prompting was allowed on a PROMPT 
request because: 

• The current source of input is an in-storage list other than an EXEC 
command procedure. 

• The NOPROMPT attribute is specified in the user's profile table (UPT). 

• The current source of input is an EXEC command procedure running in the 
background, and there is no DATA PROMPT entry to satisfy the request. 

If PROMPT processing is allowed, the PUTGET service routine writes the first 
level message to the terminal and obtains an input line from the terminal. If the 
input line is a question mark, PUTGET either returns the next level message 
provided, or a message informing the user that no information is available. 
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PUTGET continues to respond to question marks entered from the terminal by 
writing one more second level message to the terminal in response to each 
question mark entered until the chain is exhausted; at that point PUTGET issues 
a message informing the user at the terminal that no more information is 
available. The prompt message is not repeated and the task goes into an input 
wait until the terminal user enters a line. When a line is obtained from the 
terminal, PUTGET places the address of the line into the fourth word of the 
PGPB. 

Note that for message prompting, PUTGET with TERMGET = EDIT is required. 

Input Line Format - The Input Buffer 

The fourth word of the PUTGET parameter block contains zeros until the 
PUTGET service routine returns a line of input. The service routine places the 
requested input line into an input buffer beginning on a doubleword boundary 
located in subpool 1 . It then places the address of this input buffer into the 
fourth word of the PGPB. The input buffer belongs to the program that issued 
the PUTGET macro instruction. The buffer or buffers returned by PUTGET are 
automatically freed when your code relinquishes control. You may free the input 
buffer with the FREEMAIN macro instruction after you have processed or 
copied the input line. 

Regardless of the source of input, the input line returned by the PUTGET service 
routine is in a standard format. All input lines are in the variable length record 
format with a fullword header followed by the text returned by PUTGET. 
Figure 12-34 shows the format of the input buffer returned by the PUTGET 
service routine. 
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Length 
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1 




■» 
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2 Bytes 
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Figure 12-34. Format of the PUTGET Input Buffer 



The two-byte length field contains the length of the returned input line including 
the header (4 bytes). You can use this length field to determine the length of the 
input line to be processed, and later, to free the input buffer with the R form of 
the FREEMAIN macro instruction. The two-byte offset field is always set to 
zero on return from the PUTGET service routine. 



12-76 TSO/E Guide to Writing a TMP or a CP 



Figure 12-35 shows the PUTGET control block structure for a multilevel 
PROMPT message after the PUTGET service routine has returned an input line. 
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Figure 12-35. PUTGET Control Block Structure - Input Line Returned 



An Example of PUTGET 



Figure 12-36 is an example of the code required to execute the PUTGET macro 
instruction. The code uses a multilevel PROMPT message as the PUTGET 
output line. It assumes that a line of input will be returned from the terminal and 
tests only for a zero return code (PUTGET completed normally). 
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The execute form of the PUTGET macro instruction builds the I/O parameter 
list, using the addresses of the user profile table and the environment control table 
supplied in the command processor parameter list. In addition, the I/O parameter 
list contains the address of an ECB built by the code, and the address of the list 
form of the PUTGET macro instruction as the PUTGET parameter block 
address. 

Note that the TERMPUT, TERMGET, and ENTRY operands are not coded; the 
default values are used. Note also that this code is effective only if the top 
element of the input stack indicates a terminal as the current source of input. 
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Return Codes from PUTGET 



When the PUTGET service routine returns control to the program that invoked 
it, it provides one of the following return codes in general register 15. 

Code Meaning 

(decimal) 

PUTGET completed normally. 

The line obtained came from the terminal. 

4 PUTGET completed normally. 

The line obtained did not come from the terminal. (MODE messages only.) 

8 The PUTGET service routine did not complete. An attention interruption occurred during 

the execution of PUTGET, and the attention handler turned on the completion bit in the 
communications ECB. 

12 No prompting was allowed on a PROMPT request. Either the user at the terminal 

requested no prompting with the PROFILE command, or the current source of input is an 
in-storage list other than an EXEC command procedure. 

12 A line could not be obtained after a MODE request. Second level messages exist, and the 

current stack element is not a terminal, but the terminal user did not request PAUSE 
processing with the PROFILE command. The messages are, therefore, not available to 
him. 

16 The NOW AIT option was specified for TPUT and no line was put out. 

20 The NOW AIT option was specified for TGET and no line was received. 

24 Invalid parameters were supplied to the PUTGET service routine. 

28 A conditional GETMAIN was issued by PUTGET for output buffers and there was not 

sufficient space to satisfy the request. 

32 The terminal has been disconnected. 

Note: User abend 204 is issued when the return code is greater than twelve. 
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Chapter 13. Using the TGET/TPUT/TPG SVC for Terminal I/O 



SVC 93, a supervisor call routine, provides a route for program I/O to and from 
the terminal. You use the TGET, TPUT, and TPG macro instructions to invoke 
SVC 93. The basic sequential access method (BSAM), the queued sequential 
access method (QSAM), and the TSO I/O service routines all use SVC 93 to 
process terminal I/O. You may use the TGET, TPUT, and TPG macro 
instructions in any TSO routines you write, and in any application programs that 
run under TSO. However, when you use TGET, TPUT, or TPG in an 
application program, the program becomes TSO-dependent. 

In a batch environment, the only TPUTs that are processed are those with the 
ASID, ASIDLOC, or USERIDL keyword referencing an ASID or userid other 
than the current one. TGET, TPG, and other types of TPUT macros are ignored. 

The TGET, TPUT, and TPG macro instructions do not require that you build 
control blocks for their use. The operands you code into each of these macro 
instructions specify the location and size of the TGET, TPUT, or TPG buffers, 
and the SVC functions you want performed. 

The TGET and TPUT macro instructions have standard, list, execute, and 
register forms. The TPG macro has standard, list, and execute forms. 

This section discusses: 

• The TPUT macro instruction 

• The TPG macro instruction 

• The TGET macro instruction 

• Formatting the TGET/TPUT/TPG parameter registers 

• Examples of TGET and TPUT 



The TPUT Macro Instruction ~ Writing a Line to the Terminal 



Use the TPUT macro instruction (SVC 93) to transmit a line of output to the 
terminal. You can use the TPUT macro instruction in any TSO routines you 
write, and in any application programs to be run under TSO. Note, however, 
that TPUT does not provide message ID stripping, text insertion, or second level 
message chaining. If you require these features, use the PUTLINE macro 
instruction. 

The TPUT macro instruction can be issued in 24-bit or 31 -bit addressing mode. 
TPUT executes in 24-bit addressing mode. All input specified on the macro must 
reside below 16 megabytes. 
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Figure 13-1 shows the format of the TPUT macro instruction; the figure 
combines the standard, register, list, and execute forms. Each of the operands is 
explained following the figure. Appendix A describes the notation used to define 
macro instructions. 

Note: For a discussion of register contents and parameter list expansions for 
TPUT, see "TGET/TPUT/TPG Parameter Formats" later in this section. 




buffer address , buff er size 
p. EDIT 
,NOEDIT 
f ASIS 
, CONTROL 
_,FULLSCR_ 

,mf=(l 

)(E f ctrladdr) 



[~, WAIT ~[r, NOHOLD ] I", 
L/NOWAITJLfHOLD J \_, 



NOBREAK 
BREAKIN 



[",HIGHPl 
[, LOWP J 



,ASID=id 

,ASIDLOC=address 
i _,USERIDL=address. 



Figure 13-1. The TPUT Macro Instruction ~ Standard, Register, List, and Execute Forms 

buffer address 

Standard form: The address of the buffer that holds your line of output. 
You may specify any label valid in an RX instruction, or place the address 
of the label in one of the general registers 1-12, and then specify that 
register within parentheses. 

Register form: The register that contains the parameters to be passed in 
register 1 to the TPUT SVC. When the R format is specified, this operand 
must be in one of the general registers 1-12, and that register specified 
within parentheses. 

buffer size 

Standard form: The size of the output buffer in bytes. The allowable range 
is from through 32,767 bytes. A buffer size of results in no data being 
transmitted to the terminal. You can specify this buffer size directly as a 
number, or you can place the buffer size into one of the general registers 0, 
or 2-12, and specify that register within parentheses. 

Register form: The register that contains the parameters to be passed in 
register to the TPUT SVC. When the R format is specified, this operand 
must be in one of the general registers or 2-12, and that register specified 
within parentheses. 



Notes: 



If the registers you specify as the first and second operands in the 
register form of TPUT are registers 1 and respectively, the TPUT 
macro instruction will expand directly into the TGET/TPUT/TPG SVC. 
However, if you use registers 2-12, the macro expansion will load 
registers 1 and from the registers you specify before issuing the SVC. 
Therefore, you might find it advantageous to use registers 1 and 0. 
(The expansion destroys the contents of registers 1 and 0.) 
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2. If QSAM is used for terminal I/O and a data set is defined with 
BLKSIZE = 80 and RECFM = U, each line will be truncated by 1 
character. This byte (the last byte) is reserved for an attribute 
character. 



R 



Indicates that this is the register form of the TPUT macro instruction. You 
must place the parameters you want passed to the TPUT SVC into two 
registers and specify those registers as the first two operands of the macro 
instruction. 

The R operand and all other optional operands are mutually exclusive. 

If both R and any other optional operands are coded, the macro will not 
expand. 

MF = 

Indicates the form of the TPUT macro instruction. 

L 

Specifies the list form. 

(E,ctrl addr) 

Specifies the execute form and the address of the list form. 

EDIT 

Indicates that in addition to minimal editing (see ASIS), the following 
TPUT functions are requested: 

1. All trailing blanks are removed before the line is written to the terminal. 
If a blank line is sent, the terminal vertically spaces one line. 

2. Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 

3. All terminal control characters (except backspace) are replaced with a 
printable character. 

4. Only those characters that appear in USA EBCDIC keyboard layout 
and code charts are supported. All others are replaced with a printable 
character. The replacement of characters includes the representation of 
the keyboard features and national characters without hexadecimal 
equivalents of the USA EBCDIC code. 

EDIT is the default value for the EDIT, ASIS, CONTROL, FULLSCR, 
and NOEDIT operands. 

NOEDIT 

Indicates that, if the terminal is an IBM 3270 display, the message is 
transmitted completely unedited. It is assumed that the command processor 
using this option has structured the data stream with the necessary 
commands to perform the display function. For LU_T1 terminals, this 
option is converted to ASIS. 
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ASIS 



Indicates that minimal editing is to be performed by the TPUT SVC as d 

follows: 



1 . The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to prevent 
program caused I/O errors. This does not mean that all unprintable 
characters are eliminated. For example, restore, uppercase, lower case, 
bypass, and bell ring might be valid but unprintable characters at some 
terminals. (See CONTROL.) 

2. Transmission control characters are added. 

3. An EBCDIC NL, placed at the end of the message, indicates to the 
TPUT SVC that the cursor is to be returned at the end of the line. NL 
is replaced with whatever is necessary to cause the cursor to return for 
that particular terminal type. This NL processing occurs only if you 
specify ASIS, and if the NL is the last character in your message. 

If you specify EDIT, NL is handled as described in item 3 under EDIT. 

If the NL is embedded in your message, a semicolon or colon may be 
substituted for NL and sent to the terminal. No idle characters are 
added (see item 6 below). This may cause overprinting, particularly on 
terminals that require a line-feed character to position the carrier on a 
new line. 

4. If you have used backspace in your output message, but the backspace 
character does not exist on the terminal type to which the message is 
being routed, the backspace character is removed from the output 
message. 

5. If the output line is longer than the terminal line size, control characters 
are added as needed to cause the message to display on several lines. 

6. A sufficient number of idle characters is added to the end of each 
output line to prevent the transmission of output to the terminal while 
the cursor is being returned to the left-hand margin. 

7. Including a bypass character, bypass carriage return, or bypass new-line 
character in the TPUT macro data suppresses printing of the next input 
entered by the user at the 3270 terminal. VTAM moves the cursor to 
the next available line, unlocking the keyboard. No more data is sent 
to the terminal until the terminal user enters data or presses the 
ENTER key. The data entered by the user is not printed at the 
terminal. 

CONTROL 

Indicates that this line is composed of terminal control characters and does 
not display or move the cursor on the terminal. This option should be used 
for transmission of characters such as bypass, restore, or bell ring. See item 
7 under ASIS for additional information. 
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FULLSCR 

Indicates that, for IBM 3270 display terminals, the message will be 
transmitted essentially unedited. The FULLSCR option is designed to 
allow you to use special features of the 3270 system. For any other terminal 
type, this option is treated exactly as ASIS. With the FULLSCR option, 
only the following editing is performed: 

1 . If the first character in your message is an escape control character 
(X'27'), the two following characters are treated as a command code 
and as a write control character by the 3270. Note that the command 
code should always be for a remote 3270. If necessary, TPUT will 
convert the code to that for a local 3270. If the first character is not an 
escape character, a default write command and a write control character 
are added to the beginning of the message. Any attachment-dependent 
characters required for correct transmission of the data stream are 
provided by the access method. 

2. Transmission control characters (SOH, STX, ETX, ETB, EOT, and 
NAK) and characters having no 3270 equivalent (X'04\ X'06\ X'14' 
through X'17', and X'24') are converted to printable colons to prevent 
program-caused I/O errors. 

Lines are not counted when you use this option. 

If the OWAITHI value specified in your TSO parameters is not large 
enough to contain your entire message, or if the BUFFERS and 
BUFFERSIZE parameters are specified so that your message does not fit 
into all of the system's buffers, the TPUT operation does not proceed, and 
code X'10' is returned. For a description of OWAITHI, refer to SPL: 
Initialization and Tuning. Without the FULLSCR option, your TPUT 
proceeds buffer-by-buffer as buffers become available. 

If FULLSCR is specified for a message destined for another terminal, ASIS 
will be used instead. 

WAIT 

Specifies that control is not returned to the program that issues the TPUT 
macro instruction until the output line is placed into a terminal output 
buffer. If no buffers are available, the issuing program is placed into a wait 
state until buffers become available, and the output line is placed into them. 
WAIT is the default value for the WAIT and NOW AIT operands. 

NOWAIT 

Specifies that control is returned to the program that issues the TPUT 
macro instruction, whether or not a terminal output buffer is available for 
the output line. If no buffer is available, the TPUT SVC returns a code of 
04 in register 15. 

NOHOLD 

Indicates that control is returned to the program that issues the TPUT 
macro instruction as soon as the output line is placed in terminal output 
buffers. 

NOHOLD is the default value for the NOHOLD and HOLD operands. 
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HOLD 

Specifies that the program that issues the TPUT macro instruction cannot 
continue its processing until this output line is written to the terminal or 
deleted. The TPUT macro with the HOLD option is not discarded during 
RESHOW processing. 

NOBREAK 

Specifies that if the user starts to enter input, the user is not interrupted. 
The output message is placed on the output queue and displayed after the 
user completes the line. 

NOBREAK is the default value for the NOBREAK and BREAKIN 
operands. 

BREAKIN 

Specifies that output has precedence over input. If the user starts to enter 
input, he is interrupted, and this output line is displayed. Any data received 
before the interruption is displayed following this output line. 

HIGHP 

Specifies that this message must be sent to the terminal, even though the 
destination terminal does not display messages from other terminals. This 
operand counters the effect of the interterminal communication bit when the 
bit is set by the TERMINAL command. (The HIGHP operand is used by 
the SEND subcommand of OPERATOR and the SEND operator 
command.) The operand is recognized only if the issuing task is authorized 
(via system key, supervisor state, or APF). The ASID keyword must also 
be specified. HIGHP is the default if neither HIGHP nor LOWP is 
specified, and if the issuing program is authorized. 

LOWP 

Specifies that, if the user of the destination terminal allows interterminal 
messages, this TPUT will be sent to the terminal. (TPUT tests the 
interterminal communication bit in the terminal status block.) If such 
messages are not allowed, the message is not displayed, and a code of X'OC 
is returned, indicating that the message was not displayed. The LOWP 
operand is recognized only when ASID is specified. The issuer must be 
authorized (via system key, supervisor state, or APF). 

If LOWP is specified, the issuing program should have an alternate method 
of transmitting the message to the terminal user. For example, a message 
data set could be used. 

ASID, ASIDLOC, or USERIDL 

Specifies the ASID (address space identifier) of the target terminal, the 
address of that ASID, or the address of a field that contains a user ID. 
This facility is used for supervisor communication with the terminal and for 
inter-user communication among terminals (the SEND command). If you 
specify ASID, you must supply an ASID number. The ASID is located in 
the two-byte JSCBTJID field of the job step control block. If you use 
ASIDLOC, you must supply the address of the halfword that contains the 
ASID. If you use USERIDL, you must supply the address of the eight- byte 
field that contains the user ID f The user ID must be left-justified and, if 
necessary, padded with blanks. ASID, ASIDLOC, or USERIDL can be 
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specified in a register (2-12), and must be right-justified. The register 
number must be enclosed in parentheses. If USERIDL is used, the 
NOHOLD option is both required and the default if not specified. 

ASID, ASIDLOC, and USERIDL are invalid when you specify them with 
FULLSCR or ASIS parameters. 

Note: Normally, a program invokes TPUT to issue a message to the user 
running that program ~ that is, ASID, ASIDLOC, and USERIDL are not 
specified. If that program is run in the background, the TPUT has no 
effect. If the TPUT specifies an ASID or userid, the message is sent to the 
target terminal. ASID and USERID TPUTs from programs not in 
supervisor state or not authorized under APF are prefixed with a plus sign 
( + ) by SVC 93 to prevent possible counterfeiting of system messages to an 
operator console. 



Return Codes from TPUT 



When it returns control to the program (foreground or background) that invoked 
it, the TPUT SVC supplies one of the following return codes in general register 
15: 

Code Meaning 

(hexadecimal) 

00 TPUT completed successfully. 

04 NOW AIT was specified and no terminal output buffer was available. 

08 An attention interruption occurred while the TPUT SVC routine was processing. 

The message was not sent. 

0C A TPUT macro instruction with an ASID operand was issued but the user, 

indicated by the ASID, requested that interterminal messages not be printed on his 
terminal. The message was not sent. 

10 Invalid parameters were passed to the TPUT SVC. 

14 The terminal was disconnected and could not be reached. 



The TPG Macro Instruction - Writing a Line Causing Immediate 
Response 



Use the TPG macro instruction (SVC 93) to transmit a line of output to the 
terminal if that line of output will cause the device to respond immediately with 
input. The main use of TPG is to perform the Query function for a user who has 
included a Read Partition Structured field. TPG NOEDIT creates an outbound 
request unit with an associated change direction indicator to allow the device to 
go into send state. This data is not inspected. A TGET macro must be issued to 
retrieve the query response. 

You can use the TPG macro instruction in any TSO routines you write, and in 
any application programs to be run under TSO. 

Note: The TPG macro instruction is designed specifically to allow you to use the 
special features of the IBM 3279. 
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The TPG macro instruction can be invoked in either 24-bit or 31 -bit addressing 
mode. TPG executes in 24-bit addressing mode. All input specified on the macro 
must reside below 16 megabytes. 

Figure 13-2 shows the format of the TPG macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. For a discussion of parameter list expansions 
for TPG, see "TGET/TPUT/TPG Parameter Formats" later in this section. 



[symbol] 


TPG 




buffer address, buf f er size 

~ r ,NOEDITl [,WAIT "I [\nOHOLd] "" 
L,NOWAITj [/HOLD J 

["[ ,mf=/l \i 

L \(E,ctrladdr)JJ 





Figure 13-2. The TPG Macro Instruction — Standard, List, and Execute Forms 

buffer address 

Standard form: The address of the buffer that holds your output data. 
You may specify any address valid in an RX instruction, or place the 
address in one of the general registers 1-12, and then specify that register 
within parentheses. 

buffer size 

Standard form: The size of the output buffer in bytes. The allowable range 
is from through 32,767 bytes. A buffer size of results in no data being 
transmitted to the terminal. You can specify this buffer size directly as a 
number, or you can place the buffer size into one of the general registers 0, 
or 2-12, and specify that register within parentheses. 

Note: The R format may not be used for the TPG macro. 

NOEDIT 

Indicates that, if the terminal is an IBM 3270 display, the message is 
transmitted completely unedited. The command processor using this option 
must structure the data stream with the necessary commands to perform the 
display function (by including the command, write control character, 
structured fields,...). The command processor should supply only the data 
stream. Any attachment-dependent characters (such as X'27' for 
bisynchronous devices) are provided by the access method. For LU_T1 
terminals, this option is treated exactly like the ASIS option of the TPUT 
macro. 

Note: NOEDIT is the default, and only, mode for the TPG macro. If 
NOEDIT is omitted, a comma must be used. 



WAIT 



Specifies that control is not returned to the program that issued the TPG 
macro instruction until the output line is placed into a terminal output 
buffer. If no buffers are available, the issuing program is placed into a wait 
state until buffers become available, and the output line is placed into them. 
WAIT is the default value for the WAIT and NOW AIT operands. 
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NOWAIT 

Specifies that control is returned to the program that issued the TPG macro 
instruction, whether or not a terminal output buffer is available for the 
output line. If no buffer is available, the TPG SVC returns a code of 04 in 
register 15. 

NOHOLD 

Indicates that control is returned to the program that issued the TPG macro 
instruction as soon as the output line is placed in terminal output buffers. 

NGHOLD is the default value for the NOHOLD and HOLD operands. 

HOLD 

Specifies that the program that issued the TPG macro instruction cannot 
continue its processing until this output line is written to the terminal or 
deleted. 

MF = 

Indicates the form of the TPG macro instruction. 

L 

Specifies the list form. 

(E,ctrl addr) 

Specifies the execute form and the address of the list form. 

Note: If a TPG macro is coded in a background program, the TPG is 
ignored. 



Return Codes from TPG 



When it returns control to the program (foreground or background) that invoked 
it, the TPG SVC supplies one of the following return codes in general register 15: 

Code Meaning 

(hexadecimal) 

00 TPG completed successfully. 

04 NOWAIT was specified and no terminal output buffer was available. 

08 An attention interruption occurred while the TPG SVC routine was processing. The 

message was not sent. 

10 Invalid parameters were passed to the TPG SVC. 

14 The terminal was disconnected and could not be reached. 
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The TGET Macro Instruction — Getting a Line from the Terminal 



Use the TGET macro instruction to read a line of input from the terminal. A line 
of input is defined as all the data between the beginning of the input line and a 
line-end delimiter. A line-end delimiter is any character or combination of 
characters that causes the cursor to return to the left-hand margin on a new line, 
or that terminates transmission from the terminal. 

You can use the TGET macro instruction in any TSO routine, and in any 
application program that is run under TSO. Note, however, that TGET does not 
provide access to in-storage lists, nor does it perform any type of logical line 
processing on the returned line. If you require these features, use the GETLINE 
macro instruction. 

Each time TGET returns control to your program, register 1 contains the number 
of bytes of data actually moved from the terminal to your input buffer. If your 
buffer is smaller than the line of input entered at the terminal, only as much of 
the input line as can be contained in the input buffer is moved. Return code 
X'OC indicates that only part of the line was obtained by TGET. You must then 
issue as many TGET macro instructions as are required to get the rest of the line 
of input. 

The TGET macro instruction can be invoked in 24-bit or 31 -bit addressing mode. 
TGET executes in 24-bit addressing mode. All input specified on the macro must 
reside below 16 megabytes. 

Figure 13-3 shows the format of the TGET macro instruction; it combines the 
standard and the register form. Each of the operands is explained following the 
figure. Appendix A describes the notation used to define macro instructions. For 
a discussion of register contents and parameter list expansions for TGET, see 
"TGET/TPUT/TPG Parameter Formats" later in this section. 



[symbol] 


TGET 


buffer address , buff er size 


"|~, EDIT"] r, WAIT "1 
|_ r ASISj|_,NOWAITj 

r,R -l 

■ ,mf=/l \ 
L |(E,ctrladdrU_ 







Figure 13-3. The TGET Macro Instruction ~ Standard, Register, List, and Execute Forms 

buffer address 

Standard form: The address of the buffer that is to receive the input line. 
This can be any address valid in an RX instruction, or the address can be 
placed in one of the general registers 1-12, and that register specified within 
parentheses. 

Register form: The register that contains the parameters to be passed in 
register 1 to the TGET SVC. When the R format is specified, this operand 
must be in one of the general registers 1-12, and that register specified 
within parentheses. 
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buffer size 

Standard form: The size of the input buffer in bytes. The allowable range 
is from through 32,767 bytes. You can specify this buffer size directly as a 
number, or you can place the buffer size into one of the general registers 0, 
or 2-12, and specify that register within parentheses. A TGET with a 
0-length buffer size will successfully get a null line. 

Register form: The register that contains the parameters to be passed in 
register to the TGET SVC. When the R format is specified, this operand 
must be in one of the general registers or 2-12, and that register specified 
within parentheses. 

Note: If the registers you specify as the first and second operands in the 
register form of TGET are registers 1 and respectively, the TGET macro 
instruction will expand directly into the TGET/TPUT/TPG SVC. However, 
if you use registers 2-12, the macro expansion will load registers 1 and 
from the registers you specify before issuing the SVC. Therefore, you might 
find it advantageous to use registers 1 and 0. 

R 

Indicates that this is the register form of the TGET macro instruction. You 
must place the parameters you want passed to the TGET SVC into two 
registers and specify those registers as the first two operands of the macro 
instruction. 

The R operand and all other optional operands are mutually exclusive. If 
both R and any other optional operands are coded, the macro will not 
expand. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the following 
TGET functions are requested: 

1 . All terminal control characters (nongraphic characters such as bypass, 
line feed, restore, prefix and the character immediately following it) are 
removed from the data. 

2. When backspace is not used for character deletion, the horizontal tab 
(HT) and the backspace (BS) characters remain in the data. 

3. If the returned input line is shorter than the input buffer length, the 
buffer is padded with blanks. These blanks are not included in the 
character count returned in register 1 . 

EDIT is the default value for the EDIT and ASIS operands. 

ASIS 

Specifies that minimal editing is done as described below: 

1 . Transmission control characters are removed. 

2. The returned input line is translated from terminal code to EBCDIC. 
Invalid characters are compressed out of the data. 
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3. Line deletion and character deletion are performed according to the 
specifications in the terminal status block. 

4. New line (NL), cursor return (CR), and line feed (LF) characters, if 
present at the end of the line, are not included in the data count 
returned in register 1. 

5. After the input message is received, the cursor is returned to the 
left-hand margin of the next line before any output to the terminal is 
displayed. 

WAIT 

Specifies that control is not returned to the program that issues the TGET 
macro instruction until the input line is placed into your input buffer. If an 
input line is not available from the terminal, the issuing program is placed 
into a wait state until a line becomes available and is read into your input 
buffer. WAIT is the default value for the WAIT and NOW AIT operands. 

NOWAIT 

Specifies that, whether or not an input line is available from the terminal, 
control is returned to the program that issues the TGET macro instruction. 
If no line is returned, the TGET SVC returns a code of X'04' in register 15. 

MF = 

Indicates the form of the TGET macro instruction. 

L 

Specifies the list form. 

(E,ctrladdr) 

Specifies the execute form and the address of the list form. 



Return Codes from TGET 



When it returns control to the program that invokes it, the TGET SVC supplies, 
in register 1, the length of the message moved into your buffer, and, in register 15, 
one of the following return codes: 

Code Meaning 

(hexadecimal) 

00 TGET completed successfully. Register 1 contains the length of the input line read 

into your input buffer. 

04 NOWAIT was specified and no input was available to be read into your input buffer. 

08 An attention interruption occurred while the TGET SVC routine was processing. The 

message was not received. 

0C Your input buffer was not large enough to accept the entire line of input entered at 

the terminal. Subsequent TGET macro instructions will obtain the rest of the input 
line. 

10 Invalid parameters were passed to the TGET SVC. 

14 The terminal was disconnected and could not be reached. 
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TGET completed successfully. Register 1 contains the length of the input line read 
into your buffer. The data was received in NOEDIT mode. 



1C 



Your input buffer was not large enough to accept the entire line of input entered at 
the terminal. Subsequent TGET macro instructions will obtain the rest of the input 
line. The data was received in NOEDIT mode. 



TGET/TPUT/TPG Parameter Formats 



If you use the register format of the TGET or TPUT macro instruction, you must 
code the parameters you want passed to the TGET/TPUT/TPG SVC into two 
registers. Specify these two registers, enclosed in parentheses, as the first two 
operands of the TGET or TPUT macro instruction, followed by the R operand to 
indicate that you are executing the register form of the macro instruction. 

Note: For TPUT, the expansion destroys the contents of registers and 1. 

If the registers you specify as the first and second operands of the macro 
instruction are register 1 and register respectively, the TGET or TPUT macro 
instruction expands directly to the TGET/TPUT SVC. If you specify other 
permissible registers, registers 2-12, the macro expands to load registers one and 
zero from the registers you specify before issuing the SVC. The R format may 
not be used for the TPG macro. 

For the TPUT macro, the registers must be formatted as shown in Figure 13-4. 



RO 

Rl 
R15 








Address Space ID i 


ASID-TPUT only) 


Buffe 


r Size 






Flags 


Address of your Input or Output Buffer 






Address of User ID 











Figure 13-4. TPUT Parameter Registers 
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For the TGET macro, the registers must be formatted as shown in Figure 13-5. 



RO 
R1 








Rese 


rved 




-•* 

Buffer Size 
















Flags 




Address of Your Input Buffer 


^ 

















Figure 13-5. TGET Parameter Registers 



Flags/Flagl 


One 


Byte 


0... 




1... 




.0.. 




.1.. 




..0. 




..1. 




...0 




...1 






0... 




1... 




.0.. 




.1.. 




..00 




..01 




..10 




..11 



Always set to for TPUT. 
Always set to 1 for TGET. 
No user ID. 

Register 15 contains address of user ID. 
HIGHP processing is requested. 
LOWP processing is requested. 
WAIT processing is requested. 
NOWAIT processing is requested. 
NOHOLD processing is requested. 
HOLD processing is requested. 
NOBREAK processing is requested. 
BREAK processing is requested. 
EDIT processing is requested. 
ASIS processing is requested. 
CONTROL processing is requested. 
FULLSCR processing is requested. 
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If you use the execute form of the TPUT macro, the coded parameters expand 
into the parameter list shown in Figure 13-6. 





General 
Register 1 














• 


\ 






I 








+0 

Reserved 


Output Buffer Size 






+4 

Address of Your Output Buffer 


+8 

Reserved 


+C Flag 2 
(X'80') 


Flag 1 


Reserved 










RO 




<X'80') 


Reserved 













Figure 13-6. Parameter List Expansion for the Execute Form of TPUT 



If you use the standard form of the TPUT macro, you can code your parameters 
using registers or symbols. In this case, the TPUT macro expands to load the 
parameters into registers 0, 1, and 15 in the format illustrated in Figure 13-4. 

If you use the list form of the TPUT macro, the coded parameters expand into 
the parameter list shown in Figure 13-7. 



+0 

Address Space ID (ASID-TPUT only) 


Output Buffer Size 


+4 

Flag 1 


Address of Your Output Buffer 


+8 

Address of User ID 


+C 

Flag 2 


Reserved 



Figure 13-7. Parameter List Expansion for the List Form of TPUT 
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If you use the execute form of the TPG macro, the coded parameters expand into 
the parameter list shown in Figure 13-8. 





General 
Register 1 




























RO 










+0 


Address Space ID (ASID-TPUT only) 


Output Buffer Size 




+4 


Flagl 


Address of Your Output Buffer 


+8 


Address of User ID 


+C 


Flag 2 
(X'80'l 


Reserved 












X'80' 


Reserved 















Figure 13-8. Parameter List Expansion for the Execute Form of TPG 



If you use the list form of the TPG macro, the coded parameters expand into the 
parameter list shown in Figure 13-9. 



+0 


Reserved 




Output Buffer Size 


+4 




Address of Your Output Buffer 


+8 




Reserved 


+C 


Flag 2 


Flagl 


Reserved 



Figure 13-9. Parameter List Expansion for the List Form of TPG 



For Figure 13-6-Figure 13-9, Flagl is the same as that for Flags in Figure 13-4 
and Figure 13-5. Flag2 is X'01' for the NOEDIT option and X'02' for the TPG 
macro. 
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In Figure 13-10, Flags is the same as that for Flags in Figure 13-4 and 
Figure 13-5. 

If you use the standard, list, or execute form of the TGET macro, the coded 
parameters expand into the parameter list shown in Figure 13-10. 



R0 
R1 








Reserved 


Input Buffer Size 






Flags 


Address of Your Input Buffer 


Execute and Standard Form, 




. 








Reserved 


Input Buffer Size 






Flags 


Address of Your Input Buffer 


List Form 





Figure 13-10. Parameter List Expansion for the Standard, List, and Execute Forms of TGET 



Coding Examples of TGET and TPUT Macro Instructions 

The following coding examples show different ways to use the TGET and TPUT 
macro instructions. 

Examples of TPUT and TGET Using the Default Values 

Figure 13-11 shows a TPUT and a TGET macro instruction. They both use the 
default values; that is, the TPUT macro instruction defaults to EDIT, WAIT, 
NOHOLD, and NOBREAK, and the TGET macro instruction defaults to EDIT 
and WAIT. 
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Figure 13-11. Coding Example: TPUT and TGET Macro Instructions Using the Default Values 

The program issuing the TGET macro instruction is not given control until a line 
of data is returned. The default value is WAIT. If less than 130 characters are 
entered, the input buffer is padded with blanks. The default is EDIT. Remember 
that the actual length of the data in the input buffer is returned in register 1 . 



13-18 TSO/E Guide to Writing a TMP or a CP 



Example of TPUT Macro Instruction » Buffer Address and Buffer Length in Registers 

In the coding example shown in Figure 13-12 the output message buffer address 
and length are loaded into registers, and those registers coded as operands in the 
TPUT macro instruction. 

You might want to do this when, for example, the TPUT macro instruction is 
issued in a subroutine which receives, as parameters, a pointer to the message and 
the message length. 
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Figure 13-12. Coding Example: TPUT Macro Instruction Buffer Address and Buffer Length in Registers 
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Example of the TGET Macro Instruction ~ Register Format 



Figure 13-13 shows the code necessary to issue a register format TGET macro 
instruction. The buffer length, buffer address, and the option flags are loaded 
into registers zero and one. Note that the flag byte in register one is set to binary 
10000001, indicating that this is a TGET macro instruction requesting ASIS 
processing. This means that only minimal editing is performed on the input line. 
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Figure 13-13. Coding Example: TGET Macro Instruction Register Format 
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Chapter 14. Using Terminal Control Macro Instructions 



The following macro instructions allow a command processor to control terminal 
functions and attributes. 



Macro 




Instruction 


Function 


GTDEVSIZ 


Get device size 


GTSIZE 


Get terminal line size 


GTTERM 


Get terminal attributes 


RTAUTOPT 


Restart automatic line numbering or character prompting 


SPAUTOPT 


Stop automatic line numbering or character prompting 


STATTN 


Set attention simulation 


STAUTOCP 


Start automatic character prompting 


STAUTOLN 


Set automatic line numbering 


STBREAK 


Set break 


STCC 


Specify line-deletion and character-deletion characters 


STCLEAR 


Set display clear character string 


STCOM 


Set interterminal communication 


STFSMODE 


Set full-screen mode 


STLINENO 


Set line number 


STSIZE 


Set terminal line size 


STTIMEOU 


Set timeout feature 


STTMPMD 


Set terminal display manager options 


STTRAN 


Set character translation 


TCLEARQ 


Clear buffers 



Some of the terminal control macro instructions may be safely coded in a 
user-written command processor. They are: 



GTDEVSIZ 

GTSIZE 

GTTERM 

RTAUTOPT 

SPAUTOPT 

STAUTOCP 

STAUTOLN 

STFSMODE 

STLINENO 

STTMPMD 

STSIZE 

TCLEARQ 



The other macro instructions are intended for system use and are not 
recommended for inclusion in user-written command processors. These macros 
are used in the IBM-supplied PROFILE and TERMINAL commands. 
Inappropriate use of the following macros can cause terminal errors: 



STATTN 

STBREAK 

STCC 

STCLEAR 

STCOM 

STTIMEOU 

STTRAN 
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Except for the GTSIZE, RTAUTOPT, SPAUTOPT, and STAUTOCP macros, all 
terminal control macros must be issued in 24-bit addressing mode. Note that all 
services invoked by the terminal control macros execute in 24-bit addressing 
mode. 



GTDEVSIZ - Get Device Size 



Use the GTDEVSIZ macro instruction to determine the current logical line size 
and the number of lines of a user's terminal. This macro returns both values 
regardless of the terminal type (that is, display or non-display). See the 
description of the GTSIZE macro, which you can use to obtain the screen length 
for display stations only. 

When GTDEVSIZ is issued in a time-sharing environment, the logical line size of 
the user's terminal (that is, the maximum number of characters per line) is 
returned in register 1. The logical screen length (that is, the number of lines per 
display) is returned in register 0. If there is no maximum number of lines, register 
contains all zeros. 

The GTDEVSIZ macro is applicable only in a VTAM time-sharing environment. 
It is ignored if VTAM is not active when the macro instruction is issued. 

Figure 14-1 shows the format of the GTDEVSIZ macro instruction. 



[symbol] 



GTDEVSIZ 



Figure 14-1. The GTDEVSIZ Macro Instruction 

When control is returned to the user, register 15 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. The contents of registers and 1 are described above. 

04 Parameter specified to the SVC. No parameter should be specified. 



GTSIZE -- Get Terminal Line Size 



Use the GTSIZE macro instruction to determine the current logical line size of 
the user's terminal. When GTSIZE is executed in the background, it will return a 
line size of 132 characters and a screen size of lines. If the terminal is a display 
station, use the GTSIZE macro instruction to determine the size of the display 
screen. See the description of the GTDEVSIZ macro, which you can use to 
obtain the screen length for both display and non-display stations. 

When the GTSIZE macro instruction is issued in a time sharing environment, the 
logical line size of the user's terminal (that is, the maximum number of characters 
per line) is returned in register 1 . If the terminal is a display station, the line size 
is returned in register 1 and the screen length (that is, the maximum number of 
lines per display) is returned in register 0. If the terminal is not a display station, 
register will contain all zeros. The GTSIZE macro instruction is ignored if TSO 
is not active when the macro instruction is issued. 
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Figure 14-2 shows the format of the GTSIZE macro instruction. 



[symbol] 



GTSIZE 



Figure 14-2. The GTSIZE Macro Instruction 



When control is returned to the user, register 1 5 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 



00 
04 



Successful. The contents of registers and 1 are described above. 
Parameter specified to the SVC. No parameter should be specified. 



GTTERM - Get Terminal Attributes 



Use the GTTERM macro instruction to determine the primary (default) and the 
alternate screen sizes for a 3270 display terminal. Use the ERASE/WRITE 
command (X'F5') to erase the screen, to set the screen size mode to primary 
mode, and optionally to write data to the screen. Use the ERASE/WRITE 
ALTERNATE command (X'7E') to erase the screen, to set the screen size mode 
to the alternate mode, and optionally to write data to the screen. Figure 14-3 
shows the format of the GTTERM macro instruction. 



symbol 



GTTERM 



PRMSZE=addr [ ,ALTSZE=addr ] 
[ ,ATTRIB=addr] 



,MF=JL n 

| (E,ctraddr)£J 



Figure 14-3. The GTTERM Macro Instruction 



PRMSZE = addr 

Specifies the address of a 2-byte area into which GTTERM returns the 
primary row value in the high-order byte and the primary column value in 
the low-order byte. 

ALTSZE = addr 

Specifies the address of a 2-byte area into which GTTERM returns the 
alternate row value in the high-order byte and the alternate column value in 
the low-order byte. 

ATTRIB = addr 

Specifies the address of a 1-word field into which GTTERM returns 
terminal attributes. The contents of this field are described below: 



Byte 


Bits 


Values 


Meaning 


0-2 






Reserved 


3 


0-5 




Reserved 




6 

7 



1 

1 


The device supports EBCDIC code. 

The device supports ASCII code. 

The Read Partition (Query) is not supported 

The Read Partition (Query) is supported. 



Note: If ATTRIB is specified, you do not have to code PRMSZE or 
ALTSZE. 
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MF = 

Indicates the form of the GTTERM macro instruction. 

L 

Specifies the list form. 

(£,ctrladdr) 

Specifies the execute form and the address of the list form. 

If you use the list form of the GTTERM macro, the coded parameters expand 
into the parameter list shown in Figure 14-4. 



+ 



+ 4 



Address of halfword to receive primary screen size 



Address of halfword to receive alternate screen size 



Address of word to receive Device Query supported flag 



Figure 14-4. Parameter List Expansion for the List Form of GTTERM 

When control is returned to the user, register 1 5 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

08 Terminal in use is not a display terminal. 

0C Required PRMSZE parameter was not specified. 



RTAUTOPT — Restart Automatic Line Numbering or Character Prompting 



Use the RTAUTOPT macro instruction to restart either the automatic line 
numbering feature or the automatic character prompting feature. (The feature 
was suspended when the terminal user caused an attention interruption or entered 
a null line of input.) Since only one of these features can be used at a time, the 
restarted feature is the one that was suspended. (See the STAUTOLN macro 
instruction for a description of the automatic line numbering feature and the 
STAUTOCP macro instruction for a description of the automatic character 
prompting feature.) 

When this macro instruction is used to restart automatic line numbering, the first 
line number assigned after line numbering is restarted is the same line number 
that would have been assigned to the next line of terminal input if automatic line 
numbering had not been suspended. 

If the application program is creating a line numbered data set, use of the 
STAUTOLN macro to specify the starting number is recommended when 
restarting automatic line numbering. This will insure that the application's 
numbers are still in synchronization with the system's. 

The RTAUTOPT macro instruction is used only in a time sharing environment. 
If you issue this macro when TSO is not active or when you are running under 
Session Manager, it is ignored. 
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Figure 14-5 shows the format of the RTAUTOPT macro instruction. 



[symbol] RTAUTOPT 



Figure 14-5. The RTAUTOPT Macro Instruction 

When control is returned to the user, register 15 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. Either automatic line numbering or automatic character prompting has 

been restarted. 

04 Parameter specified to the SVC. No parameter should be specified. 

08 Invalid request. Either automatic line numbering or automatic character prompting 

was never started or never suspended, or an SPAUTOPT macro instruction has been 
issued to stop automatic line numbering or automatic character prompting. 



SPAUTOPT — Stop Automatic Line Numbering or Character Prompting 



Use the SPAUTOPT macro instruction to stop either the automatic line 
numbering feature or the automatic character prompting feature. Since only one 
of these features can be used at a time, the active feature is the feature that is 
stopped. (See the STAUTOLN macro instruction for a description of the 
automatic line numbering feature, and the STAUTOCP macro instruction for a 
description of the automatic character prompting feature.) 

The system can suspend automatic prompting when the terminal user causes an 
attention interruption or enters a null line of input. This macro should then be 
issued by the application program in its attention exit, or as the result of a zero 
length input line received via TGET. When stopped by the SPAUTOPT macro, 
prompting cannot be restarted by use of the RTAUTOPT macro. Prompting 
must be restarted by the STAUTOLN or STAUTOCP macro. 

The SPAUTOPT macro instruction is used only in a time sharing environment. If 
you issue this macro when TSO is not active or when you are running under 
Session Manager, it is ignored. 

Figure 14-6 shows the format of the SPAUTOPT macro instruction. 



[symbol] 



SPAUTOPT 



Figure 14-6. The SPAUTOPT Macro Instruction 
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When control is returned to the user, register 1 5 contains one of the following 
return codes: 



Hexadecimal 
Code 

00 



04 
08 



Meaning 

Successful. Either automatic line numbering or automatic character prompting has 
been stopped. 

Parameter specified to the SVC. No parameter should be specified. 

Invalid request. Either automatic line numbering or automatic character prompting 
was never started. 



ST ATTN - Set Attention Simulation 



Use the ST ATTN macro instruction to specify how a terminal user can interrupt 
the execution of his program without using an attention key. The TERMINAL 
command issues the ST ATTN macro when the terminal user requests that 
simulated attention be set up. 

When the ST ATTN macro instruction assigns a value to an operand, that value 
remains in effect until another STATTN macro instruction assigns a new value to 
the operand, or until the terminal user logs off. Issuing the STATTN macro 
instruction without specifying any operands results in a NOP instruction. 

The STATTN macro instruction is used only in a time sharing environment with 
terminals that use TSO through TCAM. It is ignored if TSO is not active when 
the macro instruction is issued. 

Figure 14-7 shows the format of the STATTN macro instruction. Each of the 
operands is explained following the figure. If an operand is not specified, its 
current status is not changed. 



[symbol] 


STATTN 




~LINES= I integer) ~| T TENS= (integer)"] 
",INPUT= (address)! 



Figure 14-7. The STATTN Macro Instruction 

LINES = 

Indicates the output line count (if any) that determines when a terminal user 
can interrupt the execution of his program. 

integer 

Specifies an integer from 1 through 255. This integer indicates the 
number of consecutive lines of output that can be directed to the 
terminal before the keyboard will unlock to let the terminal user 
interrupt the execution of his program. 
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Indicates that output line count will not be used to determine when 
the terminal user can interrupt the execution of his program. 

The LINES operand applies only to terminals that are not display 
stations. However, the display user may cause a simulated attention 
interruption at the bottom of the screen (that is, after every 6, 12, or 
15 lines of consecutive output, depending on screen size). 

TENS = 

Indicates whether or not locked keyboard time will be used to determine 
when a terminal user can interrupt the execution of his program. 

integer 

Specifies an integer from 1 through 255. This integer indicates the 
tens of seconds (that is, from 10 to 2550 seconds) of locked keyboard 
time that can elapse before the keyboard will unlock to let the 
terminal user interrupt the execution of his program. 







Indicates that locked keyboard time will not be used to determine 
when the terminal user can interrupt the execution of his program. 



INPUT = 

Indicates whether or not a character string will be used to determine when a 
terminal user can interrupt the execution of his program. 

address 

Specifies the address of a character string from one to four EBCDIC 
characters long, left-justified and padded to the right with blanks if 
less than four characters long. When this character string is 
encountered as the only data in a line, input processing is interrupted 
to let the program take an attention exit. (See the description of the 
ST AX macro instruction.) This string will not be recognized if it is 
preceded by any other character, including line delete or character 
delete control characters. 



Indicates that no character string will be used to determine when the 
terminal user can interrupt the execution of his program. 

When control is returned to the user, register 1 5 will contain the following return 
code: 

Hexadecimal 

Code Meaning 

00 Successful 

08 Invalid terminal type. This macro instruction should not be issued for terminals that 

use VTAM. 



Chapter 14. Using Terminal Control Macro Instructions 14-7 



STAUTOCP - Start Automatic Character Prompting 



Use the STAUTOCP macro instruction to start automatic character prompting. 
Automatic character prompting signals the terminal user when the system is ready 
to accept input from the terminal. This signal consists of putting out at the 
terminal either an underscore and a backspace or a period and a carriage return, 
depending on the type of terminal being used. The STAUTOCP macro has no 
effect with a display station, since the terminal user is always prompted for input 
by the start-of-message symbol. 

This macro instruction can be used to have the system automatically prompt the 
user for input. It is used, for example, by the INPUT subcommand of EDIT. 

Once started, automatic prompting is handled as follows: When the system has 
received a line of input, it immediately sends back to the terminal the next 
character prompt. If the program should send output while automatic prompting 
is in effect, the prompt will be repeated after all output has been set to the 
terminal. For example: 

line of input 

OUTPUT MSG FROM PROGRAM 

Automatic prompting is designed to be used by a program operating in input 
mode (that is, issuing successive TGET macros). 

The system suspends automatic prompting when the terminal user causes an 
attention interruption or when he enters a null (nonprinting) line of input. The 
application program then takes appropriate action in an attention exit routine, or 
after receiving a zero length input via the TGET macro instruction. The 
application program can stop the prompting or line numbering function via 
SPAUTOPT, or restart the function via STAUTOCP. 

The STAUTOCP macro instruction is used only in a time sharing environment. 
It is ignored if issued by a batch task or if you are running under Session 
Manager. 

Figure 14-8 shows the format of the STAUTOCP macro instruction. 



[symbol] 



STAUTOCP 



Figure 14-8. The STAUTOCP Macro Instruction 

When control is returned to the user, register 15 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 Parameter specified to the SVC. No parameter should be specified. 
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STAUTOLN - Start Automatic Line Numbering 



Use the STAUTOLN macro instruction to start automatic line numbering. 
Automatic line numbering displays a line number at the beginning of each line. 

This macro instruction can be used to have the system automatically prompt the 
user for input. It is used, for example, by the INPUT subcommand of the EDIT 
command. 

Once started, automatic line numbering is handled as follows: when the system 
has received a line of input, it immediately sends back to the terminal the next 
line number. If the program should send output while automatic line numbering 
is in effect, the line number will be repeated after all output has been set to the 
terminal. For example: 

00030 line of input 

00040 OUTPUT MSG FROM PROGRAM 

00040 

Automatic line numbering is designed to be used by a program operating in input 
mode (that is, issuing successive TGET macros). 

The system displays a new line number for each line of input received. The 
current line number maintained by the system is decremented appropriately 
whenever the input queue is cleared by a TCLEARQ macro or as the result of an 
attention interruption. The application program is responsible for numbering the 
lines independently, if it is creating a line numbered data set. The system line 
number is not available to the application program. 

The system suspends automatic line numbering when the terminal user causes an 
attention interruption or when he enters a null (nonprinting) line of input. The 
application program then takes appropriate action in an attention exit routine, or 
after receiving a zero length input via the TGET macro instruction. The 
application program can stop the line numbering function via SPAUTOPT, or 
restart the function via STAUTOLN or RTAUTOPT. You should use 
STAUTOLN rather than RTAUTOPT to restart automatic line numbering if the 
application program is numbering the input lines it receives. This choice will 
insure that the program's numbers are still in synchronization with the system's 
numbers. 

The STAUTOLN macro instruction is used only in a time sharing environment. 
It is ignored if issued by a batch task or if you are running under Session 
Manager. 

Figure 14-9 shows the format of the STAUTOLN macro instruction. Each of the 
operands is explained following the figure. 



[symbol] 


STAUTOLN 


S=address, I=address 



Figure 14-9. The STAUTOLN Macro Instruction 
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s = 



STBREAK -- Set Break 



indicates the address of a fullword that contains the number to be assigned 
to the first line of terminal input. This number can be any integer from 
through 99,999,999. 



1 = 



indicates the address of a fullword that contains the increment value to be 
used when assigning line numbers to lines of terminal input. This number 
can be any integer from through 99,999,999. 

When control is returned to the user, register 15 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. A line number will be printed out at the beginning of each line of input. 

04 Invalid parameter specified - values out of range. 



Use the STBREAK macro instruction to indicate whether the transmit interrupt 
feature on an IBM 1050, 2741, 3270, 3767, or 3770 terminal will be used or 
suppressed. The transmit interrupt feature lets terminal output processing 
interrupt terminal input processing. 

The TERMINAL command issues this macro when the terminal user specifies the 
BREAK or NOBREAK operand of the command. 

The transmit interrupt feature is a special feature on 1050 and 2741 terminals; it is 
a standard feature on the 3767, 3770, and 3270 display terminals. Specifying 
STBREAK YES for a 1050 without the transmit interrupt feature could result in 
loss of output or a permanent error at the terminal. 

When the transmit interrupt feature is being used by the system, the terminal user 
can enter the next line while the previous one is being processed. All 33/35 
Teletypes and IBM 3270, 3767, and 3770 terminals are handled this way. 1050s 
and 2741s that have been defined in the TCAM message control program as 
having the transmit interrupt feature will be handled this way (unless STBREAK 
NO is specified). 

Note: For 2741s, 3767s, 3770s, TWX, and WTTY devices supported by VTAM, 
the keyboard will remain unlocked when STBREAK NO is specified. 

When the feature is in use, terminal handling of input and output is as follows: if 
no output is available for the terminal, and if there are sufficient TSO terminal 
buffers available, the keyboard will be unlocked to allow the user to enter input. 
If the user's program generates output (TPUT) before he has started to enter 
data, the read operation is halted and the break (transmit interrupt) feature can 
be used to lock the keyboard and condition the communications line to transmit 
output. If the user has already started to type when the TPUT is issued, the 
output will not be sent until he has finished that line of input. If, however, the 
TPUT had specified the BREAKIN option, the output message would interrupt 
any input in progress. If the application does not issue a TCLEARQ macro to 
flush the input buffer queue, the interrupted input from a 1050 or a 2741 terminal 
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will be printed out again after the output is sent, to let the user continue to type 
from the point where he had been interrupted. If the application does not issue a 
TCLEARQ macro to flush the input buffer queue, the interrupted input from a 
3767, 3270, or a 3770 terminal is received by the application program but is not 
printed at the terminal. 

When the transmit interrupt feature is not being used by the system, a 1050 or 
2741 terminal keyboard is unlocked only after the user's program has issued a 
TGET request for input. (A 3270, 3767, or 3770 terminal keyboard's normal 
state is unlocked.) In this mode of operation, the terminal user cannot type ahead 
of his program. A TPUT with the BREAKIN option cannot interrupt input. 
The output will not be sent until the terminal user has completed entering his 
current input line. All display stations are handled in this way. All 1050s and 
2741s that have been defined in the TCAM message control program as not 
having the transmit interrupt feature will be handled this way. 

The STBREAK macro instruction is used only in a time sharing environment. It 
is ignored if TSO is not active when the macro instruction is issued. 

Figure 14-10 shows the format of the STBREAK macro instruction. 



[symbol] 


STBREAK 




[YESl 
NO 





Figure 14-10. The STBREAK Macro Instruction 

YES 

Indicates that the transmit interrupt feature will be used. YES is the 
default. 



NO 



Indicates that the transmit interrupt feature not be used. 



When control is returned to the user, register 1 5 will contain one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 

08 Invalid terminal type. This macro instruction should be issued only for the IBM 1050, 

2741, 3270, 3767, or 3770 terminal. 
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STCC ~ Specify Terminal Control Characters 



Use the STCC macro instruction to specify what control characters will be used to 
delete a character or a line of terminal input. 

The PROFILE command issues this macro when a terminal user requests a new 
line or character deletion character. The PROFILE command also causes the 
newly defined characters to be included in the user's profile in the user attribute 
data set (UADS). Each time the user logs on, the terminal monitor program will 
issue the STCC macro, specifying the characters in the UADS at the start of the 
session. If the terminal user does not use the PROFILE command to change the 
line or character-deletion characters, the system-supplied defaults are always used. 
A description follows. 

When the line-delete control character specified in the STCC macro instruction is 
encountered within a line of terminal input, the line control character and all the 
preceding characters in that line are deleted. When the character-delete control 
character specified in the STCC macro instruction is encountered within a line of 
terminal input, the character delete control character and the character 
immediately preceding it are deleted from the line. 

When the user is logging on, he can delete a line or character by using the 
system-supplied defaults. The defaults, according to type of terminal, are as 
follows: 

Type of Terminal Desired Action Key(s) to be Pressed 

1050 and 2741 line deletion or Attention key and backspace 

character deletion 

33/35 Teletypei line deletion or CTRL and X key (hex' 18'), back arrow ( < -), or 

character deletion underscore (_)» depending on keyboard. (Either 
key results in hex '6D'.) 

3767/3770 line deletion or Attention key and backspace 

character deletion 



No defaults are defined for the display stations, because the terminal user can use 
cursor control keys more effectively to delete characters or lines before the input 
is transmitted to the system. 

The STCC macro instruction is valid in a time sharing environment with 
terminals (other than LU_T1 devices) that use TSO with the exception that 
ATTN/NATN is not supported in a VTAM environment. STCC is ignored if 
TSO is not active when the macro instruction is issued. 

Figure 14-11 shows the format of the STCC macro instruction; each of the 
operands is explained following the figure. 



1 Trademark of the Teletype Corporation. 
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[symbol] 


STCC 




"attn" 

NATN 




: L ic-}] 


"CD=/X'n'r 
_ l C ' c J. 





Figure 14-11. The STCC Macro Instruction 

ATTN 

When this operand is in effect, depressing the ATTENTION key after 
having typed data will only delete the current line. System response is !D. 
Automatic prompting is not turned off. The ATTENTION key can then be 
depressed again, without typing any input, to interrupt the program and 
turn off prompting. When this operand is not in effect, the attention key 
will both delete a line of terminal input and interrupt the execution of the 
user's program. System response is ! or !I. 

NATN 

Indicates that the attention key will not be used to delete a line of terminal 
input. 

LD = 

Indicates what character will be used for the line delete control character: 

XV 

Where n is the hexadecimal representation of any EBCDIC character 
on the terminal keyboard, except the new line (NL) and carrier return 
(CR) control characters. If X'OO' is specified, the previously used 
line-delete control character is retained. If X'FF' is specified, no 
character will be used for the line-delete control character. If an 
invalid character is specified, that character is rejected and no 
character is used to delete a line of terminal input. 

CV 

Where c is the character representation of any EBCDIC character on 
the terminal keyboard. 

CD = 

Indicates what character will be used for the character delete control 
character: 

X'n' 

Where n is the hexadecimal representation of any EBCDIC character 
on the terminal keyboard except the new line (NL) and carrier return 
(CR) control characters. If X'OO' is specified, the previously used 
character delete control character is retained. If X'FF' is specified, no 
character will be used for the character delete control character. If an 
invalid character is specified, that character is rejected and no 
character is used to delete a character from a line of terminal input. 

C'c' 

Where c is the character representation of any EBCDIC character on 
the terminal keyboard. 

When control is returned to the user, the low-order byte of register contains the 
former line delete control character. If X'FF' appears in the low-order byte of 
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register 0, there is no former line delete control character. If X'80' appears in the 
high-order byte of register 0, ATTN was in effect for line deletion prior to the 
issuance of the STCC macro. 

The low-order byte of register 1 contains the former character delete control 
character. If X'FF' appears in the low-order byte of register 1, there is no former 
character delete control character. 

Register 15 contains one of the following return codes: 



Hexadecimal 




Code 


Meaning 


00 


Successful. 


04 


Invalid parameters specified to the SVC. 


08 


Invalid request. Specified character does 



oc 



ATTN was specified for a terminal that does not have an attention key. 
Invalid terminal type. 



STCLEAR - Set Display Clear Character String 



Use the STCLEAR macro instruction to specify the character string that will be 
used to request that a 2260 or 2265 display station screen be erased. The 
TERMINAL command issues this macro when the user specifies the character 
string he wants. 

The STCLEAR macro instruction is used only in a time sharing environment. It 
is ignored if TSO is not active when the macro instruction is issued. 

Figure 14-12 shows the format of the STCLEAR macro instruction. Each of the 
operands is explained following the figure. 



[symbol] 


STCLEAR 


STRING=/address\ 

\ ° f 



Figure 14-12. The STCLEAR Macro Instruction 

STRING = 

Indicates the address of a one- to four-character string that will be used to 
request that the display station screen be erased. This character string must 
be left-justified and padded on the right with blanks, if necessary. If is 
specified, no character string will be used to erase the screen. 

When control is returned to the user, register 15 contains one of the following 
return codes: 



Hexadecimal 
Code 

00 
04 
08 



Meaning 

Successful. 

Invalid parameter. 

Invalid terminal type. The terminal is not a display station. 
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STCOM — Set Inter-Terminal Communication 



Use the STCOM macro instruction to specify whether or not a terminal will 
accept messages from other terminals or low priority messages from the system 
operator. High priority operator messages are always sent to the terminal. The 
PROFILE command issues this macro when the user specifies the INTERCOM 
or NOINTERCOM operand of the command. 

The STCOM macro instruction is used only in a time sharing environment. It is 
ignored if TSO is not active when the macro instruction is issued. 

Figure 14-13 shows the format of the STCOM macro instruction. 



[symbol] 


STCOM 


["yes" 

[ NO 





Figure 14-13. The STCOM Macro Instruction 

YES 

Indicates that the terminal will accept messages from other terminals. If 
neither YES nor NO is specified, YES is assumed. 



NO 



Indicates that the terminal will not accept messages from other terminals. 



When control is returned to the user, register 1 5 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 



STFSMODE - Set Full-Screen Mode 



Use the STFSMODE macro instruction under VTAM to specify whether an IBM 
3270 display terminal is to operate in full-screen mode. Operating in full-screen 
mode provides screen protection by preventing the screen from being overlaid by 
non-full-screen messages, and allowing the terminal user to read non-full screen 
messages before they are overlaid by full-screen messages. If full-screen mode is 
set off, full-screen TPUT requests (that is, TPUT requests that specify the 
FULLSCR operand) can result in certain problems at the terminal. A message 
not expected by the terminal user or the command processor, such as a broadcast 
message or password request, might not be noticed by the terminal user and might 
be quickly overlayed by a full-screen display. An unexpected message might 
overlay part of a full-screen display, which could result in invalid input to the 
command processor. 

The STFSMODE macro instruction may be used only in a VTAM time-sharing 
environment. It is ignored if VTAM is not active when the macro instruction is 
issued. See Appendix B for additional information about the use of the 
STFSMODE macro and the full-screen environment. 

Figure 14-14 shows the format of the STFSMODE macro instruction. 
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[symbol] 



STFSMODE 



["ON "1 r,INITIAL=YESl T,NOEDIT=YES] [ ,RSHWKEY=n] [~, PARTION=YES| 
[OFFJ [, INITIAL=NO j [, NOEDIT=NO j ,PARTION=NO j 



Figure 14-14. The STFSMODE Macro Instruction 

ON 



Indicates that full-screen mode is in operation. If neither ON nor OFF is 
specified, ON is assumed. When a terminal operating in full-screen mode is 
to receive a non-full-screen message (TPUT without FULLSCR), the display 
screen is cleared, the alarm is sounded (if the Audible Alarm special feature 
is installed), and the message is displayed on the screen. If several such 
messages occur one after the other, the screen is cleared once, the alarm is 
sounded, and the messages are displayed in sequence. When the next 
full-screen TPUT message (TPUT with FULLSCR) is issued by the 
application, the terminal user will be required to acknowledge the messages 
on the screen before the TPUT FULLSCR can be displayed. Three 
asterisks (***) displayed at the current line indicate that acknowledgement is 
required. To continue, the user must press the ENTER key. 

OFF 

Indicates that full-screen mode is not in operation. When a terminal that is 
not operating in full-screen mode receives a message, the RSHWKEY is 
reset to the default, and the message is sent to the terminal according to the 
options specified in the TPUT macro, possibly overlaying the current screen 
contents. 

INITIAL = YES 

Indicates that this is the first time during the execution of a command 
processor that the command processor has entered full-screen mode. This 
operand prevents the first TPUT FULLSCR issued by the command 
processor from forcing a paging condition when the last transaction at the 
terminal was input. For example, after a user logs on and the READY 
message is displayed and the user types in the name of a command 
processor, a paging condition is not forced if INITIAL = YES was specified. 
INITIAL = YES is ignored if OFF is specified. 

INITIAL = NO 

Indicates that forced paging is to occur normally whenever a TPUT with 
FULLSCR follows a TPUT without FULLSCR. If neither INITIAL = YES 
nor INITIAL = NO is specified, INITIAL = NO is assumed. 

NOEDIT = YES 

Indicates that input from the terminal will be added to the input queue 
without being modified, regardless of the options specified on the TGET 
macro instruction. 

NOEDIT = NO 

Indicates that input from the terminal will be handled according to the 
options specified on the TGET macro instruction before it is added to the 
input queue. If neither NOEDIT = NO nor NOEDIT = YES is specified, 
NOEDIT = NO is assumed. 
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RSHWKEY 

Specifies as a decimal digit the program function (PF) key to be used as the 
reshow key. If RSHWKEY is not specified, the default value for the PA2 
key (X'6E') is used. 

PARTION = YES 

Indicates to TSO/VTAM that partitions are being used and the buffer 
address of the terminal screen is either a 14 or a 16-bit address. 

PARTION = NO 

Indicates to TSO/VTAM that partitions are not being used and the buffer 
address of the terminal screen is a 12-bit address. 



When control is returned to the user, register 15 contains one of the following 
return codes: 



Hexadecimal 
Code 

00 

04 

08 



Meaning 

Successful. 

Invalid parameter specified to the SVC. 

Invalid terminal type. This macro instruction is valid only for IBM 3270 display 
terminals that use VTAM. 



STLINENO -- Set Line Number 



Use the STLINENO macro instruction under VTAM to specify the number of the 
screen line on an IBM 3270 display terminal on which the next non-full-screen 
message should appear. (A non-full-screen message results from issuing a TPUT 
macro instruction without the FULLSCR operand.) The STLINENO macro 
instruction may also be used to specify whether the 3270 terminal is to operate in 
full-screen mode. 

The STLINENO macro instruction may be used only in a VTAM time-sharing 
environment. It is ignored if VTAM is not active when the macro instruction is 
issued. 

See Appendix B for additional information about the use of the STLINENO 
macro and the full-screen environment. 

Figure 14-15 shows the format of the STLINENO macro instruction. 



[symbol] 


STLINENO 


jLINE=number ) T,MODE=ON 
^LINELOC=address| |,MODE=OFF 





Figure 14-15. The STLINENO Macro Instruction 



LINE = 






Specifies in decimal the line number on which the next non-full-screen 
message is to appear. The line number must be a value from 1 to n where n 
is the maximum number of lines allowed for the terminal in use. Either the 
actual line number or a register (2-12, enclosed in parentheses) containing 
the line number in the low-order byte may be specified. 
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LINELOC = 

Specifies the address of a fullword whose low-order byte contains the 
number of the screen line on which the next non-full-screen message is to 
appear. Either an actual address (RX-type) or a register (2-12, enclosed in 
parentheses) containing the address may be specified. 

MODE = 

Specifies whether full-screen mode is to be set ON or OFF. If MODE is 
not specified, MODE = OFF is assumed. 



When control is returned to the user, register 1 5 contains one of the following 
return codes: 



Hexadecimal 
Code 

00 

04 

08 

0C 



Meaning 

Successful. 

Invalid parameter specified to the SVC. 

Invalid terminal type. This macro instruction is valid only for IBM 3270 display 
terminals that use VTAM. 

The line number specified was or it was greater than the maximum number of lines 
allowed for the terminal in use. 



STSIZE - Set Terminal Line Size 



Use the STSIZE macro instruction to set the logical line size of the time sharing 
terminal. 

If the terminal is a display station, the STSIZE macro instruction is used to set 
the screen size. The STSIZE macro changes only the logical screen size of a 
terminal. In non-full-screen processing, the logical and physical screen sizes are 
the same. However, in full-screen processing they are not necessarily the same 
and when they are not the same, this macro does not change the physical screen 
size of the terminal. Full-screen applications can change the physical screen size 
using the appropriate WRITE command. 

The TERMINAL command issues this macro instruction when the user specifies 
the LINESIZE or SCRSIZE operands of the command. 

The STSIZE macro instruction is used only in a time sharing environment. If you 
issue this macro when TSO is not active or when you are running under Session 
Manager, it is ignored. 

Figure 14-16 shows the format of the STSIZE macro instruction. Each of the 
operands is explained following the figure. 



[symbol] 


STSIZE 


(siZE=number ) 
(SIZELOC=addressJ 


,LINE=number 
,LINELOC=address 





Figure 14-16. The STSIZE Macro Instruction 
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SIZE 

Specify the logical line size of the terminal in characters. If the logical line 
size requested is greater than the physical line size of the terminal, the last 
character in the line may be repeatedly typed over. Specifying a size greater 
than 255 gives unpredictable results. 

SIZELOC 

Specify the address of a word containing the logical line size of the terminal 
in characters. 

LINE 

Specify the number of lines that can appear on the screen of a display 
station terminal. 

LINELOC 

Specify the address of a word containing the number of lines that can 
appear on the screen of a display station terminal. 

Note: If the terminal is a display station, either the LINE or LINELOC operand 
must be specified. If the terminal is not a display station, neither operand should 
be specified. 



Defaults by terminal type are as follows: 


Terminal Type 


Line Size, Number of Lines, or Screen Size 


2741 


120 


1050 


120 


33/35 Teletype2 


72 


2260,2265 


12x80, 12x40, 6x40, 15x64 - as specified by 




control program. 


3270 


12x40 or 24x80 


3767 


132 


3770 


132 



When control is returned to the user, register 1 5 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 

08 Invalid LINE, LINELOC, SIZE, or SIZELOC operand, as follows: 

1 . The LINE or LINELOC operand was specified for any terminal except a display 
station. (An operand value of zero is not an error, and has the same effect as 
omitting the operand.) 

2. The LINE or LINELOC operand was omitted, or specified as zero, for a display 
station. 

3. The SIZE or SIZELOC operand was omitted, or specified as zero, for any 
terminal type. 

0C The dimensions specified for a display station do not correspond to known existing 

screen size. Incorrect screen management can result. 



2 Trademark of the Teletype Corporation. 

Chapter 14. Using Terminal Control Macro Instructions 14-19 



STTIMEOU - Set Time Out Feature 



Use the STTIMEOU macro instruction to specify whether the 1050 terminal has 
the optional text time out suppression feature. The macro instruction allows 
1050s, with or without the feature, to call in via the same switched line, with any 
1050 being handled initially as if it did not have the feature. 

A 1050 without the text time out suppression feature operates as follows: When 
the PROCEED light is on and the keyboard is unlocked, the terminal will time 
out; that is, the keyboard will lock if the user does not type input for 
approximately 20 seconds. The system subsequently responds to the time out by 
restoring the keyboard so that the user may continue. The user can prevent the 
time out by periodically pressing the SHIFT key. 

A 1050 with the text time out suppression feature operates as follows: The 
keyboard does not lock if the user does not type input within 20 seconds. The 
system can therefore use the read inhibit channel command, which does not time 
out within 28 seconds, in contrast to the read channel command that does time 
out. (Note: If the system is directed to use the read inhibit channel command for 
a 1050 that does time out, the terminal may be locked out of the system.) 

Until the STTIMEOU macro instruction is issued, 1050 terminals are handled as 
per the definition provided in the TCAM message control program. If the 
currently connected terminal has the text time out suppression feature, 
STTIMEOU NO can be issued to direct the system to use read inhibit rather than 
read channel commands. (STTIMEOU NO should not be issued for a 1050 that 
does not have the text time out suppression feature. This specification could 
cause the terminal to be locked out of the system.) 

The TERMINAL command processor issues the STTIMEOU macro instruction 
when the user specifies the TIME OUT or NOTIMEOUT operand of the 
TERMINAL command. The STTIMEOU macro instruction will remain in effect 
until the user logs off. 

The STTIMEOU macro instruction should be issued only when an IBM 1050 
terminal is being used. Terminals which are equivalent to the one explicitly 
supported may also function satisfactorily. The customer is responsible for 
establishing equivalency. IBM assumes no responsibility for the impact that any 
changes to the IBM-supplied products or programs may have on such terminals. 

The STTIMEOU macro instruction is used only in a time sharing environment. 
It is ignored if TSO is not active when the macro instruction is issued. 

Figure 14-17 shows the format of the STTIMEOU macro instruction. 



[symbol] 


STTIMEOU 




YES 
NO 





Figure 14-17. The STTIMEOU Macro Instruction 
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YES 

Indicates that IBM 1050 terminal does time out. It does not have the text 
time out suppression feature. If the operand is omitted, the default is YES. 

NO 

Indicates that the IBM 1050 terminal does not time out. The 1050 does 
have the text time out suppression feature. 

When control is returned to the user, register 1 5 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 

08 Invalid terminal type. This macro instruction applies to the IBM 1050 terminal only. 



STTMPMD - Set Terminal Display Manager Options 



Use the STTMPMD macro instruction to specify whether a Display Terminal 
Manager is active or whether the PA1 and CLEAR key indications are to be 
passed through to the application program. 

The STTMPMD macro instruction is issued only in a time-sharing environment. 
It is ignored if issued for a non-TSO task. The STTMPMD macro is valid for 
display terminals operating in both the TCAM and VTAM environments. 

Figure 14-18 shows the format of the STTMPMD instruction. Each of the 
operands is explained following the figure. 



[symbol] 


STTMPMD 




"on " 

OFF 




~KEYS=(nO V 
(ALLJ 





Figure 14-18. The STTMPMD Macro Instruction 

ON 

Indicates that a Display Terminal Manager is in control. If neither ON nor 
OFF is specified, ON is the default. 

OFF 

Indicates that a Display Terminal Manager is not in control. 

KEYS = NO 

Indicates that the PA1 and CLEAR key indications are not to be returned 
to the application program. This is the default if the KEYS operand is 
omitted. 

KEYS = ALL 

Indicates that the PA1 and CLEAR key indications are to be returned to 
the application program. 
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When control is returned to the user, register 15 contains one of the following 
return codes: 



Hexadecimal 
Code 

00 
04 
08 



Meaning 

Successful. 

Invalid parameter specified. 

Invalid terminal type. This is not a display terminal. 



STTRAN -- Set Character Translation 



Use the STTRAN macro instruction to initiate the use of user-specified 
translation tables, to modify specific character translations in active translation 
tables, to remove character modifications made to user-specified translation 
tables, and to terminate the use of user-specified translation tables. Translation 
tables allow characters entered at the terminal to be interpreted as other 
characters when they are received by TSO, and characters sent by TSO to be 
interpreted as other characters when they are received at the terminal. 

The TERMINAL command issues this macro instruction when a terminal user 
specifies the TRAN, NOTRAN, CHAR, or NOCHAR operand of the command. 

Translation tables are built and used in pairs: one for input and one for output. 
Each pair is a control section consisting of a fullword containing the address of 
the output table, followed by a 256-byte EBCDIC table for translating the 
inbound characters, followed by a 256-byte EBCDIC table for translating the 
outbound characters. Each character in an input table must have a counterpart in 
its companion output table, and the characters must have the same relative 
position in both tables. Refer to SPL: TSO/E User Exits and Modifications 
Volume 2 for instructions on building translation tables. 

A translation table translates inbound data after the system translates the line 
code to EBCDIC characters. A translation table translates outbound data before 
the system translates EBCDIC characters to line code. 

The STTRAN macro instruction is used only in a VTAM time-sharing 
environment. It is ignored if VTAM is not active when the macro instruction is 
issued. 

Figure 14-19 shows the format of the STTRAN macro instruction. Each of the 
operands is explained following the figure. 



[symbol] 


STTRAN 




"( (TABLE=address,NAME=address) \" 
\ (NOTRAN j f 

J (TCHAR=address , SCHAR= address) ( 
( (NOCHAR ,NAME=addr ess f) 

[mf=/l n 

|_ | (E,ctrl addr)rl 





Figure 14-19. The STTRAN Macro Instruction 
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TABLE = address 

Specifies the address of a pair of user-written translation tables. 

NAME = address 

Specifies the address of an 8-byte area containing an EBCDIC character 
string. (The string is left-justified and padded to the right with blanks if it is 
less than eight characters long.) The character string consists of the name of 
a member in a load module that contains user-written translation tables. 

When NAME is used with NOCHAR, the STTRAN macro instruction 
causes the command processor to store the member name in the 8-byte area. 

NOTRAN 

Specifies that the use of user-written translation tables be discontinued. 

TCHAR = address 

Specifies the address of a 1-byte area containing the EBCDIC representation 
of a character as it appears at the terminal. 

SCHAR = address 

Specifies the address of a 1-byte area containing the EBCDIC representation 
of a character as it appears to the system. 

NOCHAR 

Specifies that current TCHAR and SCHAR values are no longer in effect. 

MF = 

Indicates the form of the STTRAN macro instruction. 



Specifies the list form. 

(E,ctrl addr) 

Specifies the execute form and the address of the list form. 

When control is returned to the user, register 1 5 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 NOTRAN or NOCHAR was specified but translation was not in effect. 

08 TABLE or NOCHAR was specified but the NAME operand did not specify an 

address. 

0C Internal error - unidentifiable flag set in input register 0. 
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TCLEARQ - Clear Buffers 



TCLEARQ enables the user to throw away "typed ahead" input or unsent output. 
This clearing of the buffers lets the command processor resynchronize with the 
terminal user. 

For example, when a command processor analyzes the specified operands in a line 
of input and discovers missing or invalid parameters, it issues a TCLEARQ 
INPUT before sending a prompting message to the user. This ensures that the 
command processor will receive a line of input entered after the terminal user has 
seen the prompting message. 

When the TCLEARQ macro instruction is issued to clear the input buffers, all the 
input that has been entered at the terminal, but has not yet been processed by the 
foreground job, is purged. To ensure synchronization, the terminal keyboard on a 
TCAM terminal is locked until the next TGET macro is issued. Keyboards on 
terminals that use VTAM do not lock. 

When the TCLEARQ macro instruction is issued to clear the output buffers, all 
the output that has been processed by the foreground job but not yet displayed at 
the terminal is purged. 

The TCLEARQ macro instruction is used only in a time sharing environment. It 
is ignored if TSO is not active when the macro instruction is issued. 

The TCLEARQ macro instruction is written as follows: 

Figure 14-20 shows the format of the TCLEARQ macro instruction; each of the 
operands is described following the figure. 



[symbol] 


TCLEARQ 




"input "1 

OUTPUTJ 



Figure 14-20. The TCLEARQ Macro Instruction 

INPUT 

Indicates that all input currently in the terminal's input buffer queue will be 
lost, including the input line currently being entered, if any. If neither 
INPUT nor OUTPUT is specified, INPUT is assumed. 

OUTPUT 

Indicates that all the output for this terminal that is currently in the 
terminal's output buffer queue will be purged, except for output messages 
that have begun to appear at the terminal, or messages from other terminals 
or the system operator. (Such messages are sent via the TPUT TJID macro 
instruction.) 

When control is returned to the user, register 15 contains one of the following 
return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 
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Chapter 15. Command Scan and Parse — Determining the Validity of 
Commands 



If you write your own command processors to run under TSO, you need a 
method of determining whether any command name or subcommand name 
entering the system is valid, and whether the operands following the command are 
syntactically correct. Command scan and parse are the two service routines 
provided with TSO that perform these functions. 



Command scan searches the command buffer for a valid command name, 
parse service routine scans the command buffer for operands. 



The 



In general, command scan is invoked by a terminal monitor program and the 
parse service routine is invoked by a command processor. Command scan may 
also be invoked by any command processors that process subcommands. 

Both of these service routines receive control via the CALLTSSR or LINK 
macro. Their entry points are: 

Service Routine Entry Point 



Command Scan 
Parse 



IKJSCAN 
IKJPARS 



Sequence of Operations 



If your TMP or command processor uses command scan and/or the parse service 
routine, the sequence of operations is as follows: 

1 . Your terminal monitor program or command processor gets a line of input 
which may contain a command and its operands. 

2. Your terminal monitor program or command processor uses the LINK macro 
or the CALLTSSR macro to invoke command scan (IKJSCAN) and passes it 
a parameter list containing, among other things, the address of the command 
buffer. 

3. Command scan searches the buffer for a command name, checks the syntax 
of the command name (if you request it to), updates the command buffer 
offset field to point to the command operands (if any), and returns control to 
the calling program. 

4. The calling program receives the address of the command name and gives 
control to the appropriate command processor or subcommand processor. 



Chapter 15. Command Scan and Parse - Determining the Validity of Commands 15-1 



5. The command processor invokes the parse service routine (IKJPARS) via the 
CALLTSSR or LINK macro, and passes it parameter lists containing, among 
other things, the syntactical structure of the command operands, and the 
address of the command buffer. 

6. The parse service routine scans the buffer for operands, builds a list 
describing the operands found, and returns control to the calling program. 

7. The command processor processes the command according to the operands 
received. 

8. When the command processor terminates, it returns control to the terminal 
monitor program and the sequence is repeated. 

The following sections discuss: 

• Acceptance of double-byte character set data 

• Using the command scan service routine 

• Using the parse service routine 



Acceptance of Double-Byte Character Set Data (MVS/XA Only) 



In MVS/XA only, command scan and parse accept double-byte character set 

(DBCS) strings in addition to EBCDIC character strings. The shift-out character 

(X'OE') indicates a change from EBCDIC to DBCS; the shift-in character (X'OF') / 

indicates the reverse. Each double-byte character requires a double-byte ^ 

representation so that valid DBCS strings contain an even number of bytes. With 

the exception of blank, which is X'4040', each byte has a value between X'41' and 

X'FE'. If the DBCS string contains an invalid character, parse replaces it with 

X'4195'. 

Double-byte characters can appear in comments and certain types of strings of 
user data. If the programming language you are using supports DBCS data, 
default values can also contain valid DBCS strings. DBCS strings that appear 
where they are not accepted could cause an error condition. The types of user 
strings that can contain DBCS data along with the associated parse macro and 
parameter follows: 

• Self delimiting string (STRING parameter of IKJPOSIT) 

• Quoted string (QSTRING parameter of IKJPOSIT) 

• Parenthesized string (PSTRING parameter of IKJPOSIT) 

• Value string (VALUE parameter of IKJPOSIT) 

• Quoted character constant (CONSTANT parameter of IKJTERM) 

• Quoted character string (CHAR or HEX parameter of IKJIDENT). 

Parse does not accept DBCS strings in prompting mode. In addition, you cannot 

use DBCS strings in quoted data set names, quoted passwords for data sets, or 

quoted passwords for user IDs because MVS does not accept DBCS strings in 

those cases. However, the parse macro, IKJPOSIT, treats X'OE' and X'OF' as 

DBCS delimiters in quoted data set names (DSNAME and DSTHING 

parameters), quoted passwords for data sets (DSNAME and DSTHING *\ 
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parameters), and quoted passwords for user IDs (USERID and UID2PSWD 
parameters). 

Check all hexadecimal data that you pass to parse to be sure that X'OE' and 
X'OF' represent the shift-out and shift-in characters when appropriate. 
Previously, parse treated those characters simply as hexadecimal data. Now, 
when used in the strings mentioned earlier in this topic, parse treats them as 
DBCS delimiters. Therefore, change X'OE' and X'OF' to some other values if 
they do not represent the shift-out and shift-in characters and you are passing 
them through the parse service. 



Using the Command Scan Service Routine (IKJSCAN) 



In general, a terminal monitor program links to command scan to verify 
command names. Command scan may also be invoked by the TEST program or 
by any command processors that process subcommands. It can also be used to 
scan the reply to a prompt message. 

Command scan examines a command in a command buffer and performs the 
following functions: 

1. It translates all lowercase characters in the command name to uppercase. 

2. If a valid parameter is present, it resets the offset to the number of text bytes 
preceding the first non-blank character in the operand field. If a valid 
operand is not present, the offset equals the length of the text portion of the 
buffer. 

3. It returns a pointer to the command name, the length of the command name, 
and a code explaining the results of its scan to the calling routine. 

4. It optionally checks the syntax of the command name. 

5. It recognizes an implicit EXEC command that has a percent sign as the first 
character. 

6. It has logic to handle leading blanks and embedded comments. 
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This topic discusses: 

• Command name syntax 

• The parameter list structure required by command scan 

• The command scan parameter list 

• Flags passed to command scan 

• The command scan output area 

• The operation of the command scan service routine 

• The results of the command scan 

• Return codes from command scan 



Command Name Syntax 



If you write your own command processor, and you intend to use the command 
scan service routine to check for a valid command name, your name must meet 
the following syntax requirements: 

• The first character must be an alphabetic or a national character. 

• The remaining characters must be alphameric. 

• The length of the command name must not exceed eight characters. 

• The command delimiter must be a separator character. 

• The name should include one or more numerals. Since no IBM-supplied 
command names include numerals, your command name will be unique. 
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The Parameter List Structure Required by Command Scan 



Before invoking the command scan service routine via the CALLTSSR macro, 
you must create the parameter structure shown in Figure 15-1. You then place 
the address of the command scan parameter list (CSPL) into general register 1, set 
the flags in the flag word, and issue CALLTSSR specifying IKJSCAN, the 
command scan service routine. 

IKJSCAN may be invoked in either 24- or 31 -bit addressing mode. IKJSCAN 
executes in 31 -bit addressing mode and can be passed input that resides above or 
below 16 megabytes. 





General 
Register 1 


































CSPL 








+ o 


i 
UPT 




Flag Word 




+ 4 1 


ECT 




Flags 


Reserved 




♦ . ! 


CP ECB 








+ 12 


Flag Word •-- 


/ Command Scan Output Area 






Command Name Pointer 


To be set by 

Command 

Scan 


+ 16 - 


Output Area •- 


Length 


Flags 


Reserved 


+ 20 


Command Buffer *~ 
















Command Buffer ^ 4 








Length 


Offset 


( ( 

Text 














2 4 l l 





Figure 15-1. The Parameter List Structure Passed to Command Scan 



The Command Scan Parameter List 



The command scan parameter list (CSPL) is a six-word parameter list containing 
addresses required by the command scan routine. In order to ensure the 
reenterability of the calling program, the CSPL should be built in subpool 1 in an 
area obtained by the calling program with the GETMAIN macro instruction. 



Chapter 15. Command Scan and Parse - Determining the Validity of Commands 15-5 



The CSPL is defined by the IKJCSPL DSECT. Figure 15-2 shows the format of 
the command scan parameter list. 



Number 
of Bytes 


Field 


Contents or Meaning 


4 
4 
4 

4 
4 

4 


CSPLUPT 
CSPLECT 
CSPLECB 

CSPLFLG 
CSPLOA 

CSPLCBUF 


The address of the user profile table. 

The address of the environment control table. 

The address of the command processor's event control block. 
(Required if command scan is called by a command processor to scan a 
subcommand; zeros if command scan is called by the TMP.) 

The address of a fullword, obtained via the GETMAIN macro 
instruction by the routine linking to command scan, and located in 
subpool 1 . The first byte of the word pointed to contains flags set by 
the calling routine; the last three bytes are reserved. 

The address of an 8-byte command scan output area, located in 
subpool 1. The output area is obtained by the calling routine via a 
GETMAIN macro instruction. It is filled in by the command scan 
service routine before it returns control to the calling routine. (See 
Figure 15-1.) 

The address of the command buffer. 



Figure 15-2. The Command Scan Parameter List 



Flags Passed to Command Scan 



The flag word built in subpool 1 and pointed to by the fourth word of the CSPL 
is obtained and freed by the calling routine. Only the first byte of the field is used 
by the command scan service routine; the remaining three bytes are reserved. Set 
the flag byte before linking to the command scan routine to indicate whether or 
not you want the command to be syntax checked. The flag byte has the following 
meanings: 

X'OO' Syntax check the command name. 

X'80' Do not syntax check the command name. 



The Command Scan Output Area 



The command scan service routine returns the results of its scan to the calling 
program by filling in a two-word command scan output area (CSOA). The 
CSOA must be obtained and freed by the calling program. It must be located in 
subpool 1 and its address stored into the fifth word of the command scan 
parameter list before your program links to IKJSCAN. 

The CSOA is defined by the IKJCSOA DSECT. Figure 15-3 shows the format 
of the command scan output area. 



Number 
of Bytes 


Field 


Contents or Meaning 


4 
2 
1 
1 


CSOACNM 
CSOALNM 
CSOAFLG 


The address of the command name if the command name is present and 
valid. Zero otherwise. 

Length of the command name if the command name is present and 
valid. Zero otherwise. 

A flag field. Command scan sets these flags to indicate the results of its 
scan. See Figure 15-5. 

Reserved. 



Figure 15-3. The Command Scan Output Area 
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The Operation of the Command Scan Service Routine 



If you set the flags field in the flag word to X'80' (do not syntax check the 
command name) the command scan service routine scans the buffer to determine 
if it contains a question mark or a command. The first character in the command 
buffer is checked for a question mark whether or not syntax checking is requested. 
If it is a question mark, no further scanning is done. If it is not a question mark, 
the command name is considered to begin at the first non-separator character 
found, and end at the first command delimiter character found. See Figure 15-4 
for a list of the separator characters. 

Command scan translates any lowercase letters in the command name to 
uppercase, fills the command scan output area, updates the command buffer 
offset field, and returns to the calling program. 

If you have requested syntax checking (X'OO' in the flag field of the flag word), 
the command name must meet the syntax requirements, as follows: 

• The first character must be an alphabetic or a national character. 

• The remaining characters must be alphameric. 

• The length of the command name must not exceed eight characters. 

• The command delimiter must be a separator character. 

If the flag field in the flag word is set to X'OO' (syntax check the command) and 
the user enters a percent sign (%) as the first character of a command name, 
command scan will: 

• Turn on the CSOAEXEC flag to X'04'. 

• Update the command name pointer to the next position following the percent 
sign. 

• Continue the scan. 

Figure 15-4 shows the various character types recognized by command scan and 
parse. Unless otherwise indicated, alphameric characters are: 

Alphabetic (A-Z) 
Numeric (0-9) 
National ($, #, @) 
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Character Type 










Command 






Character 




Separator 


National 


Alphabetic 


Numeric 


Delimiter 


Delimiter 


Special 


Comment 


/* 


X 














Horizontal Tab 


HT 


X 








X 






Blank 


b 


X 








X 






Comma 


, 


X 








X 






Dollar Sign 


$ 




X 












Number Sign 


# 




X 












At Sign 


@ 
a-z 
A-Z 
0-9 




X 


X 
X 


X 








New line 


NL 










X 


X 




Period 












X 




X 


Left parenthesis 


( 










X 


X 




Right parenthesis 


) 










X 


X 




Ampersand 


& 










X 




X 


Asterisk 


* 














X 


Semicolon 


; 










X 


X 




Minus sign, hyphen 


- 










X 




X 


Slash 


/ 










X 


X 




Apostrophe 












X 


X 




Equal sign 


= 










X 


X 




Cent sign 


C 














X 


Less than 


< 














X 


Greater than 


> 














X 


Plus sign 


+ 














X 


Logical OR 


! 














X 


Exclamation point 


i 














X 


Logical NOT 


-i 














X 


Percent sign 


% 














X 


Dash 


- 














X 


Question mark 


? 














X 


Colon 
















X 


Quotation Mark 


" 














X 


Shift-out 1 


X'OE' 














X 


Shift-in 1 


X'OF 














X 



l The shift-out and shift-in characters indicate the beginning and end of a string of double-byte character set data. (MVS/XA only) 
Figure 15-4. Character Types Recognized by Command Scan and Parse 



Results of the Command Scan 

The command scan service routine scans the command buffer and returns the 
results of its scan to the calling routine by filling in the command scan output 
area, and by updating the offset field in the command buffer. Figure 15-5 shows 
the possible CSOA settings and command buffer offset settings upon return from 
the command scan service routine. 
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Command Scan Output Area 


Command Buffer 


Flag 


Meaning 


Length Field 


Offset set to: 


X'80' 


The command name is valid and the 
remainder of the buffer contains 
non-separator characters. 


Length of command name 


The first non-separator following the 
command name. 


X'40' 


The command name is valid and 
there are no non-separator characters 
remaining. 


Length of command name 


The end of the buffer. 


X'20' 


The command name is a question 
mark. 


Zero 


Unchanged. 


X'10' 


The buffer is empty only separators. 


Zero 


The end of the buffer. 


X'08' 


The command name is syntactically 
invalid. 


Zero 


Unchanged. 


X'04' 


The command is an implicit EXEC 
command. 


Length of command name 


The first non-separator following the 
command line. 



Figure 15-5. Return from Command Scan - CSOA and Command Buffer Settings 



Return Codes from Command Scan 



The command scan service routine returns the following codes in general register 
1 5 to the program that invoked it: 



Hexadecimal 

Code Meaning 



Command scan completed successfully. 
Command scan was passed invalid parameters. 



Using the Parse Service Routine (IKJPARS) 



The parse service routine checks the syntax of command operands. To prepare 
for this, the command processor creates a parameter control list (PCL) — a 
description of permissible operands, default values, text to be used when 
prompting, and, if present, the address of a validity checking subroutine. 

The command processor invokes the parse service routine via the CALLTSSR or 
LINK macro, passing it a parse parameter list (PPL) which contains the address 
of the PCL. The parse service routine scans and checks each operand against the 
entries (called PCEs: parameter control entries) in the PCL. In turn, the parse 
service routine builds and returns results of the scan to the command processor in 
a parameter descriptor list (PDL), whose entries contain pointers to data set 
names, indications of specified options, or pointers to the subfields entered with 
the command operands. 

The command processor uses the IKJPARMD DSECT to refer to the PDL. The 
command processor specifies the IKJPARMD DSECT at the time it issues the 
parse macro instructions to build the PCL. The labels used by the command 
processor on the various parse macro instructions become the symbolic addresses 
of the fields in the IKJPARMD DSECT. 

IKJPARS may be invoked in either 24- or 31 -bit addressing mode. IKJPARS 
executes in 31 -bit addressing mode and can accept input above or below 16 
megabytes. 
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Figure 1 5-6 depicts a command processor's use of the parse macro instructions, 
the parse service routine, and the IKJPARMD DSECT. 



Command Buffer 



Length 


Offset 


Command Name 


Parameter 1 


Parameter 2 


Parameter 3 



Command Processor 


CALLTSSR/UNK to Parse 


0/ Issues Parse macro 
instructions to build 






a PCL describing 




valid parameters 

• label 1 Macro 

• Iabel2 Macro 

• Iabel3 Macro 

These macro 


PCL 




PCE1 


PCE2 






instructions also 
create the 




PCE3 


_ 


IKJPARMD DSECT. 

IKJPARMD 
DSECT 
Tabell ~~] 

h- - 1 

I Iabel2 j 




KUL 






PDE 








PDE 






PDE 










1 Iabel3 ■ 
1 1 

Q6y The Command 








(5) Return to the Command Processor 


Processor uses the 




IKJPARMD DSECT 




to access the various 




PDEs within the 




PDL. 











Parse Service Routine 



Q3) Compares PCE's to 
parameters in the 
Command Buffer. 



(4) Builds the PDL. 



Figure 15-6. A Command Processor Using the Parse Service Routine 

The parse service routine support consists of the following: 

1 . The following set of macro instructions: 

IKJPPL builds an IKJPPL DSECT which maps the parse parameter list. 

IKJPARM begins the parameter control list and establishes a symbolic 
reference for the parameter descriptor list. 

IKJPOSIT builds a parameter control entry. This PCE describes a positional 
parameter that contains delimiters recognized by the parse service routine, but 
not including the positional parameters described by the IKJTERM, 
IKJOPER, IKJIDENT, or IKJRSVWD macro instructions. 
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IKJIDENT also builds a parameter control entry; however, this PCE 
describes a positional parameter that does not depend upon a particular 
delimiter. 

IKJKEYWD builds a parameter control entry that describes a keyword 
parameter. 

IKJNAME describes the possible names that may be entered for a keyword 
or a reserved parameter. 

IKJTERM builds a parameter control entry. This PCE describes a positional 
parameter that may be a constant, statement number, or variable. 

IKJOPER builds a parameter control entry that describes an expression. An 
expression consists of three parts; two operands and an operator in the form: 

(operandi operator operand2) 

IKJRSVWD builds a parameter control entry. This PCE may be used with 
the IKJTERM macro instruction to describe a reserved word constant, with 
the IKJOPER macro instruction to describe the operator of an expression, or 
by itself to describe a reserved word parameter. 

IKJSUBF indicates the beginning of a keyword subfield description. 

IKJENDP indicates the end of the PCL. 

IKJRLSA releases any virtual storage (allocated by the parse service routine) 
that remains after the parse service routine has returned control to the 
command processor. 

2. A program that checks the syntax of the command operands within the 

command buffer against the PCL and builds a PDL containing the results of 
the syntax check. 

The parse service routine also provides the following services which may be 
selected by the calling routine: 

It translates the command operands to uppercase. 

It substitutes default values for missing operands. 

It prompts the user at the terminal for missing positional parameters. 

It passes control to an exit, supplied by the calling routine, to do further 
checking on a positional parameter. 

It inserts implied keywords. 

It appends user-supplied second level messages to prompting messages. 
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This section describes: 

if Command parameter syntax 

• Using the parse macro instructions to define command syntax 
#' The parse macro instructions 

• Passing control to the parse service routine 

• Formats of the PDEs returned by the parse service routine 

• Additional facilities provided by the parse service routine 

• An example of using the parse service routine 

• Return codes from the parse service routine 



Command Parameter Syntax 



Positional Parameters 



If you write your own command processors, and you intend to use the parse 
service routine to determine which operands have been entered following the 
command name, your command parameters must adhere to the syntactical 
structure described in this section. 

Command parameters must be separated from one another by one or more of the 
separator characters: blank, tab, comma, or a comment (see Figure 15-4). The 
command parameters end either at the end of a logical line (carrier return), or at 
a semicolon. If the command parameters end with a semicolon, and other 
characters are entered after the semicolon but before the end of the logical line, 
the parse service routine ignores that portion of the line that follows the 
semicolon. The parse service routine returns no message to indicate this 
condition. 

There are two types of command parameters recognized by the parse service 
routine: 

1. Positional parameters 

2. Keyword parameters 



Positional parameters must be coded first in the parameter string, and they must 
be in a specific order. 

In general, the parse service routine considers a positional parameter to be missing 
if the first character of the parameter scanned is not the character expected. For 
instance, if a parameter is supposed to begin with a numeric character and the 
parse service routine finds an alphabetic character in that position, the numeric 
parameter is considered missing. The parse service routine then prompts for the 
missing parameter if it is required, substitutes a default value if one is available, 
or ignores the missing parameter if the parameter is optional. 

For the purpose of syntax checking, positional parameters are divided into 
parameters that include delimiters as part of their definition (delimiter-dependent 
parameters), and parameters that do not include delimiters as part of their 
definition (non-delimiter-dependent parameters). 
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Delimiter-Dependent Parameters: Those parameters that include delimiters as 
part of their definition are called delimiter-dependent parameters. The parse 
service routine recognizes the following delimiter-dependent parameter syntaxes 
shown in Figure 15-7. 



Parameter 


Macro Instruction Used to Describe Parameter 


DELIMITER 

STRING 

VALUE 

ADDRESS 

PSTRING 

USERID 

UID2PSWD 

DSNAME 

DSTHING 

QSTRING 

SPACE 

JOBNAME 


IKJPOSIT 


CONSTANT 
VARIABLE 
STATEMENT NUMBER 


IKJTERM 


EXPRESSION 


IKJOPER 


RESERVED WORD 


IKJRSVWD 


HEX 
CHAR 

INTEG 


IKJIDENT 



Figure 15-7. Delimiter-Dependent Parameters 

DELIMITER 

It may be any character other than an asterisk, left parenthesis, right 
parenthesis, semicolon, blank, comma, tab, carrier return, digit, shift-out 
character (X'OE'), or shift-in character (X'OF'). A self-defining delimiter 
character is represented in this discussion by the symbol #. The delimiter 
parameter is used only in conjunction with the string parameter. 

STRING 

A string is the group of characters between two alike self-defining delimiter 
characters, such as 

#string# 

or, the group of characters between a self-defining delimiter character and 
the end of a logical line, such as 

#string 

The same self-defining delimiter character can be used to delimit two 
contiguous strings, such as 

#string#string# 



or 



#string#string 

A null string, which indicates that a positional parameter has not been 
entered, is defined as two contiguous delimiters or a delimiter and the end 
of the logical line. If the missing string is a required parameter, the null 
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string must be entered as two contiguous delimiters. Note that a string 
received from a prompt or a default must not include the delimiters. See 
"Acceptance of Double-Byte Character Set Data (MVS/XA Only)" for 
information about using double-byte character set data in a self-delimiting 
string. 

VALUE 

A value consists of a character followed by a string enclosed in apostrophes, 
such as 

X'string' 

The character must be an alphabetic or national character. The string may 
be of any length and may consist of any combination of enterable 
characters. If the ending apostrophe is left off the string, the parse service 
routine assumes that the string ends at the end of the logical line. If the 
parse service routine encounters two successive apostrophes, it assumes them 
to be part of the string and continues to scan for a single ending 
apostrophe. The parse service routine always raises the character preceding 
the first apostrophe to uppercase. The value is considered missing if the 
first character is not an alphabetic or national character, or if the second 
character is not an apostrophe. See "Acceptance of Double-Byte Character 
Set Data (MVS/XA Only)" for information about using double-byte 
character set data in a value string. 

ADDRESS 

There are several forms of the ADDRESS parameter. 

Absolute address 

An absolute address consists of from one to six hexadecimal digits 
followed by a period, or, in extended mode, from one to eight 
hexadecimal digits followed by a period. An extended absolute 
address must not exceed the address represented by the hexadecimal 
value 7FFFFFFF. (For more information on extended addressing, 
see the description of the EXTENDED operand in "IKJPOSIT - 
Describing a Delimiter-Dependent Positional Parameter" below.) 

Relative address 

A relative address consists of from one to six hexadecimal digits 
preceded by a plus sign, or, in extended mode, from one to eight 
hexadecimal digits preceded by a plus sign. 

General register address 

A general register address consists of a decimal integer in the range 
to 15 followed by the letter R. R can be entered in either uppercase 
or lowercase. 

Floating-point register address 

A floating-point register address consists of an even decimal integer in 
the range to 6 followed by the letter D (for double precision) or E 
(for single precision). The letter E or D can be entered in either 
uppercase or lowercase. 
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Symbolic address 

A symbolic address consists of any combination, up to 32 characters 
in length, of the alphameric characters and the break character. The 
first character must be either an alphabetic or a national character. 

Qualified address 

A qualified address has one of the following formats: 



1 . modulename . entryname . relative-address 

2. modulename. entryname 

3 . modulename. entryname . symbolic-address 

4. .entryname. symbolic-address 

5. . entryname. relative-address 

6 . . entryname 



• modulename - any combination of one to eight alphameric 
characters, of which the first is an alphabetic or national character 

• entryname - same syntax as a modulename, and always preceded 
by a period 



• symbolic address 
by a period 



syntax as defined above, and always preceded 



• relative address 
a period 



syntax as defined above, and always preceded by 



You may qualify symbolic or relative addresses to indicate that they 
apply to a particular module and CSECT as in formats 1-3. However, 
if the address applies to the currently active module, you do not have 
to specify modulename, as in formats 4-6. 

Indirect address 

An indirect address is an absolute, relative, symbolic, or general 
register address followed by from one to 255 indirection symbols. 
When the EXTENDED keyword is specified on the IKJPOSIT macro, 
the user may specify the 31 -bit indirection symbol, ?. The 24-bit 
indirection symbol, %, may also be specified. If EXTENDED is not 
specified, the user is limited to using the 24-bit indirection symbol. 

Note: In the following examples, hash marks indicate that the byte is 
not used to determine the 24-bit address. 
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Figure 15-8 shows an example of an indirect address that is made up 
of a relative address with one level of 24-bit indirect addressing. 



+A% 

RELATIVE LOC+A 




Figure 15-8. Example of 24-Bit Indirect Addressing 

The number of indirection symbols following the address indicates the 
number of levels of indirect addressing. In Figure 15-8, the data is at 
the location pointed to by bits 0-24 of relative address + A. 

Figure 15-9 shows how the substitution of a 31 -bit indirection symbol, 
?, changes the result of the resolution of an indirect address. The 
example assumes that EXTENDED has been specified on IKJPOSIT. 

+A% 

RELATIVE LOC+A 



23 


00 


OC 


2C 



LOC23000C2C 



DATA 



Figure 15-9. Example of 31-Bit Indirect Addressing 

Figure 15-10 shows an example of an indirect address in which 24- 
and 31 -bit indirection symbols are combined. The example assumes 
that EXTENDED has been specified on IKJPOSIT. 

In Figure 15-10, four levels of indirect addressing are processed to 
resolve the indirect address. 
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+A%??% 



RELATIVE LOC+A 
V 




LOC BC8 



00 


00 


01 


48 




LOC 148 



01 


00 


A0 


94 




Figure 15-10. An Indirect Address with Mixed Indirection Symbols 



Address expression 

An address expression has one of two formats, depending on whether 
the EXTENDED keyword is specified on the IKJPOSIT macro. 

EXTENDED not specified: 

An address expression has the following format when EXTENDED 
has not been specified: 



address { +} expression value [%...][{ ±} expression value [%...]].'.. 



• address - can be an absolute, symbolic, indirect, relative, or 
general register address. If a general register is specified, it must 
be followed by at least one indirection symbol. 

• expression value - a plus or minus displacement from an address 
in storage, consisting of from one to six decimal or hexadecimal 
digits 

— Decimal displacement is indicated by an "N" or "n" following 
the offset. The absence of an "N" or "n" indicates 
hexadecimal displacement. 
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- There is no limit to the number of expression values in an 
address expression. 

• Each expression value may be followed by from one to 255 
percent signs, one for each level of indirect addressing. 

For example, addrl + 124n, an address expression in decimal format, 
indicates a location 124 decimal bytes beyond addrl. Another 
example, addr2-AC, is an address expression in hexadecimal format 
and indicates a location 1 72 decimal bytes before addr2. 

The processing of an address expression, 12R%% + 4N%, involving 
24-bit indirect addressing, is shown in Figure 15-11. The address in 
the expression is a general register address with two levels of indirect 
addressing. The result of the processing of this part of the address 
expression is location 1D0. The expression value indicates a 
displacement of four bytes beyond location 1D0 with one level of 
indirect addressing. The data, then, is at location 474. 



1 2R%%+4N% 
R12 



//A 00 01 28 




LOC1D0 



+4 











# 


00 


04 


74 



LOC 474 



DATA 



Figure 15-11. An Address Expression with 24-Bit Indirect Addressing 



Note: Blanks are not allowed Within any form of the address 
parameter. 
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EXTENDED specified: 

An address expression has the following format when EXTENDED 
has been specified: 



address { ± } expression 



value rr%"l 1 r{,±} expression value|rr%~| "1 ~| 



• address - can be an absolute, symbolic, indirect, relative, or 
general register address. If a general register is specified, it must 
be followed by at least one indirection symbol. 

• expression value - a plus or minus displacement from an address 
in storage, consisting of a one to ten digit decimal number, or a 
one to eight digit hexadecimal number. 

— Decimal displacement is indicated by an "N" or "n" following 
the offset. The absence of an "N" or "n" indicates 
hexadecimal displacement. 

— There is no limit to the number of expression values in an 
address expression. 

• Each expression value may be followed by from one to 255 
indirection symbols (including any valid combination of question 
marks and percent signs), one for each level of indirect addressing. 

The processing of an address expression involving both 24- and 3 1 -bit 
indirect addressing is shown in Figure 15-12. 
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Figure 15-12. An Address Expression with Mixed Indirection Symbols 



PSTRING 

A parenthesized string is a string of characters enclosed within a set of 
parentheses, such as: 

(string) 

The string may consist of any combination of characters of any length, with 
one restriction; if it includes parentheses, they must be balanced. The 
enclosing right parenthesis of a PSTRING can be omitted if the string ends 
at the end of a logical line. 

A null PSTRING is defined as a left parenthesis followed by either a right 
parenthesis or the end of a logical line. See "Acceptance of Double-Byte 
Character Set Data (MVS/XA Only)" for information about using 
double-byte character set data in a parenthesized string. 
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USERID 

A user ID consists of an identification optionally followed by a slash and a 
password. The format is: 

identification [/password] 

identification 

Can be any combination of alphameric characters up to seven 
characters in length, the first of which must be an alphabetic or 
national character. 

password 

Can be any combination of alphameric characters up to eight 
characters in length. If delimiters are used, the password must be 
enclosed in quotes. If quotes are to be used in the password, two 
quotes must be entered consecutively. One of them will be eliminated 
by the parse service routine. 

Separators may be inserted between the identification and the slash, and 
between the slash and the password. 

If just the identification is entered, the parse service routine does not prompt 
for a password. If the identification is entered followed by a slash and no 
password, the parse service routine prompts for a password by executing a 
PUTGET macro instruction specifying bypass mode. The terminal user can 
reply to a prompt for password by entering either a password or a null line. 
If the user enters a null line, the parse service routine builds the PDE and 
leaves the respective password field zero. 

UID2PSWD 

A user ID consists of an identification optionally followed by two 
passwords. The delimiter between the three values is a slash. The format is: 

identification [/passwordl [/password2] ] 

identification 

Can be any combination of alphameric characters up to seven 
characters in length, the first of which must be an alphabetic or 
national character. 

passwordl 

Can be any combination of alphameric characters up to eight 
characters in length. If delimiters are used, the password must be 
enclosed in quotes. If quotes are to be used in the password, two 
quotes must be entered consecutively. One of them will be eliminated 
by the parse service routine. 

password2 

Same as passwordl. 

IKJPOSIT generates a variable length parameter control entry (PCE). 
Within the PCE, a field contains a hexadecimal number indicating the type 
of positional operand described by the PCE. For UID2PSWD, the 
hexadecimal number is C. 
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DSNAME 

The data set name parameter has three possible formats: 



dsname [ (membername) ] [/password] 
[dsname] (membername) [password] 
'dsname [ (membername)] ' [/password] 



dsname 

May be either a qualified or an unqualified name. 

An unqualified name is any combination of alphameric characters up 
to eight characters in length, the first character of which must be an 
alphabetic or national character. 

A qualified name is made up of several unqualified names, each 
unqualified name separated by a period. A qualified name, including 
the periods, may be up to 44 characters in length. 

membername 

One to eight alphameric characters, the first of which must be an 
alphabetic or a national character. 

Note: The parse service routine considers the entire dsname parameter 
missing if the first character scanned is not an apostrophe, an alphabetic 
character, a national character, or a left parenthesis. If the VOLSER option 
is specified, the first character may be numeric. 

If it is numeric, only six characters are accepted for VOLSER. VOLSER is 
valid only for DSNAME or DSTHING. If USERID is specified, the parse 
service routine will prefix all data set names not entered in quotes with the 
user identification (from the UPT). 

If the slash and the password are not entered, the parse service routine does 
not prompt for the password. If the slash is entered and not the password, 
the parse service routine prompts for the password by executing a PUTGET 
macro instruction specifying bypass mode; that is, the terminal user's reply 
will not print at the terminal. 

DSTHING 

A DSTHING is a dsname parameter as previously defined except that an 
asterisk can be substituted for an unqualified name or for each qualifier of a 
qualified name. The parse service routine processes the asterisk as if it were 
a dsname. The asterisk is used to indicate that all data sets at that 
particular level are considered. 

Note: If the first character of a dsname is an asterisk, the parse service 
routine will not prefix the USERID. 
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QSTRING 

A quoted string is a string of characters enclosed within apostrophes, such 
as: 

'string' 

The string can consist of any length combination of characters, with one 
restriction: if the user wishes to enter apostrophes within the string, two 
successive apostrophes must be entered for each single apostrophe desired; 
one of the apostrophes is removed by the parse service routine. 

The ending apostrophe is not required if the string ends at the end of the 
logical line. 

A null quoted string is defined as two contiguous apostrophes or an 
apostrophe at the end of the logical line. See "Acceptance of Double-Byte 
Character Set Data (MVS/XA Only)" for information about using 
double-byte character set data in a quoted string. 

SPACE 

Space is a special purpose parameter; it allows a string parameter that 
directly follows a command name to be entered without a preceding 
self-defining delimiter character. The space parameter must always be 
followed by a string parameter. If the delimiter of the command name is a 
tab, the tab is the first character of the string. The string always ends at the 
end of the logical line. 

JOBNAME 

The jobname may have an optional job identifier. Each job identifier is a 
maximum of eight alphameric characters of which the first is alphabetic or 
national. There is no separator character between the jobname and job 
identifier. The syntax is jobname (jobid). 

CONSTANT 

There are several forms of the constant parameter. 

Fixed-point numeric literal - Consists of a string of digits (0 through 9) 
preceded optionally by a sign ( + or -), such as: 

+ 1234.43 

This literal may contain a decimal point anywhere in the string except as the 
rightmost character. The total number of digits cannot exceed 18. 
Embedded blanks are not allowed. 

Floating-point numeric literal - Takes the following form: 

+ 1234.56E+10 

This literal is a string of digits (0 through 9) preceded optionally by a sign 
( + or -) and must contain a decimal point. This is immediately followed by 
the letter E and then a string of digits (0 through 9) preceded optionally by 
a sign ( + or -). Embedded blanks are not allowed. The string of digits 
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preceding the letter E cannot be greater than 16 and the string following E 
cannot be greater than 2. 

Non-numeric literal - Consists of a string of characters from the EBCDIC 
character set, excluding the apostrophe, and enclosed in apostrophes, 
entered as: 

'numbers (1234567890) and letters are ok' 

The length of the string excluding apostrophes may be from 1 to 120 
characters in length. 

Figurative constant - Is one of a set of reserved words supplied by the caller 
of the parse service routine such as: 

test!23 

A figurative constant consists of a string of characters up to 255 in length. 
Embedded blanks are not allowed. All characters of the EBCDIC character 
set are allowed except the blank, comma, tab, semicolon, and carrier return, 
however, the first parameter must be alphabetic. See "Acceptance of 
Double-Byte Character Set Data (MVS/XA Only)" for information about 
using double-byte character set data in a quoted character constant. 

VARIABLE 

The following is the form of the variable parameter. 



[program-id. ] data-name 


"(OF) qualification" 

w 

_ (subscript) 





Program-id 

Consists of the first eight characters of a program identifier followed 
by a period. The first character must be alphabetic (A through Z) and 
the remaining characters must be alphabetic or numeric (0 through 9): 

Data-name 

Consists of a maximum of 30 characters of the set: 

A through Z (alphabetic) 
through. 9 (numeric) 
- (hyphen) 

typically entered as: 

mydataset-123 

The data-name cannot begin or end with a hyphen and must contain 
at least one alphabetic character. 

here55.mydataset-123 
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Qualification 

Is applied by placing after a data-name one or more data-names 
preceded by the qualifiers IN or OF, entered as: 

mydataset-123 of yourdataset-456 

The number of qualifiers that can be entered for a data-name is 
limited to 255. 

Subscript 

Consists of a data-name with subscripts enclosed in parentheses 
following the data-name entered as: 

yourdataset-456 (mydataset-123) 

A separator between the data-name and the subscript is optional. 
Subscripts are a list of constants or variables. 

The number of subscripts that can be entered for a data-name is 
limited to 3, entered as: 

here55(abcdefhl5) 

A separator character between subscripts is required. 

STATEMENT NUMBER 

The following is the form of a statement number: 

[program id. ] line number [.verb number] 
An example is: 

here.23.7 
where: 

Program id 

Consists of the first eight characters of a program identifier followed 
by a period. The first character must be alphabetic (A through Z) and 
the remaining characters must be alphameric (A through Z or 
through 9). 

Line number 

Consists of a string of digits (0 through 9) and cannot exceed a length 
of 6 digits. 

Verb number 

Consists of one digit (0 through 9) that is preceded by a period. 

Embedded blanks are not allowed in a statement number. 
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EXPRESSION 

An expression takes the form: 

(operandi operator operand2) 

The operator in the expression shows a relationship between the operands, 
such as: 

(a be equals 123) 

An expression must be enclosed in parentheses. An expression is defined by 
the IKJOPER macro. The operands are defined by the IKJTERM macro, 
and the operator by the IKJRSVWD macro instruction. 

RESERVED WORD 

Has three uses depending on the presence or absence of operands on the 
IKJRSVWD macro instruction. The uses are: 

• When used with the RSVWD keyword of the IKJTERM macro 
instruction, the IKJRSVWD macro identifies the beginning of a list of 
reserved words, any one of which can be entered as a constant. 

• When used with the RSVWD keyword of the IKJOPER macro 
instruction, the IKJRSVWD macro identifies the beginning of a list of 
reserved words, any one of which can be an operator in an expression. 

• When used by itself, the IKJRSVWD macro instruction defines a 
positional reserved word parameter. 

Note: The IKJRSVWD macro instruction is followed by a list of 
IKJNAME macros that contain all of the possible reserved words used as 
figurative constants or operators. 

The HEX, CHAR, and INTEG operands on the IKJIDENT macro describe 
delimiter positional parameters. 

• HEX - indicates that any quantity of the form X'nn', 'ABC (quoted 
string), or any nonquoted character string in which case a separator or 
delimiter indicates the end, will be accepted as valid data. See 
"Acceptance of Double-Byte Character Set Data (MVS/XA Only)" for 
information about using double-byte character set data in a quoted 
string of characters. 

• CHAR - indicates that any data in the form of a quoted or nonquoted 
string will be accepted as valid data. See "Acceptance of Double-Byte 
Character Set Data (MVS/XA Only)" for information about using 
double-byte character set data in a quoted string of characters. 

• INTEG - indicates that any numeric character in the following form will 
be converted by the parse service routine to its appropriate binary value. 

(X'nn') - where n is a valid hexadecimal digit(A-F,0-9), maximum of 8. 

(B'mm') - where m is a valid binary bit (0-1), maximum of 32. 

dddddd - decimal digits (0-9), maximum of 10. 

Note: The maximum decimal value for INTEG is 2147843647. 
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Positional Parameters Not Dependent on Delimiters: A positional parameter that 
is not dependent on delimiters is passed as a character string with restrictions on 
the beginning character, additional characters, and length. These restrictions are 
passed to the parse service routine as operands on the IKJIDENT macro 
instruction. 

The parse service routine recognizes the following character types as the beginning 
character and additional characters of a non-delimiter-dependent positional 
parameter: 

ALPHA 

Indicates an alphabetic or national character. 

NUMERIC 

Indicates a number (0-9). 

ALPHANUM 

Indicates an alphabetic or national character or a number. 

ANY 

Indicates that the character to be expected can be any character other than 
a blank, comma, tab, semicolon, or carrier return. A right parenthesis must, 
however, be balanced by a left parenthesis. 

NONATABC 

Indicates an alphabetic character only is accepted. (No national characters.) 

NONATNUM 

Indicates numbers and alphabetic characters are accepted. (No national 
characters.) 

An asterisk can be entered in place of any positional parameter that is not 
dependent on delimiters. 

Entering Positional Parameters as Lists of Ranges: You may want to have some 
positional parameters of your command entered in the form of a list, a range, or a 
list of ranges. The macro instructions that describe positional parameters to the 
parse service routine, IKJPOSIT, IKJTERM and IKJIDENT, provide a LIST 
and a RANGE operand. If coded in the macro instruction, they indicate that the 
positional parameters expected can be in the form of a list or a range. 

LIST 

Indicates to the parse service routine that one or more of the same type of 
positional parameters may be entered enclosed in parentheses as follows: 

(positional-parameter positional-parameter. . . ) 

If one or more of the items contained in the list are to be entered enclosed 
in parentheses, both the left and the right parenthesis must be included for 
each of those items. 
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The following positional parameter types may be used in the form of a list: 

VALUE 

ADDRESS 

USERID 

UID2PSWD 

DSNAME 

DSTHING 

JOBNAME 

CONSTANT 

STATEMENT NUMBER 

VARIABLE 

HEX 

CHAR 

INTEG 

Any positional parameters that are not dependent upon delimiters 

RANGE 

Indicates to the parse service routine that two positional parameters are to 
be entered separated by a colon as follows: 

positional-parameter : positional-parameter 

The following positional parameter types may be used in the form of a 
range or a list of ranges: 

HEX (form X' ' only) 

ADDRESS 

VALUE 

CONSTANT 

STATEMENT NUMBER 

VARIABLE 

INTEG 

Any positional parameter that is not dependent upon delimiters 

If the user at the terminal wants to enter a parameter that begins with a left 
parentheses, and you have specified in either the IKJPOSIT or IKJIDENT macro 
instruction that the parameter can be entered as a list or a range, the user must 
enclose the parameter in an extra set of parentheses to obtain the correct result. 

For instance, you have specified via the IKJPOSIT macro instruction that the 
dsname operand may be entered as a list, and the terminal user wishes to enter a 
dsname of the form: 

{membername) /password 

He must enter it as: 

( (membername) /password) 
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Keyword Parameters 



Keyword parameters can be entered anywhere in the command as long as they 
follow all positional parameters. They may consist of any combination of 
alphameric characters up to 3 1 characters long, the first of which must be an 
alphabetic character. 

You describe keyword parameters to the parse service routine with the 
IKJKEYD, IKJNAME and IKJSUBF macro instructions. 

Keyword parameters can have other parameters associated with them. These 
parameters, known as subfields, must be enclosed in parentheses directly following 
the keyword. A subfield may contain positional as well 
as keyword parameters. In the following example posnl and kywd2 are 
parameters in the subfield of keyword 1: 

keywordl (posnl kywd2 ) 

The same syntax rules that apply to commands apply within keyword subfields. 

• Keyword parameters must follow positional parameters. 

• Enclosing right parenthesis may be eliminated if the subfield ends at the end 
of a logical line. 

• The subfield may not contain unbalanced right parentheses. 

If a keyword with a subfield in which there is a required parameter is entered 
without the subfield, the parse service routine prompts for the required parameter. 
The terminal user must not include the subfield parentheses when he enters the 
required parameter. 

If a subfield has a positional parameter that can be entered as a list, and if this is 
the only parameter in the subfield, the list must be enclosed by the same 
parentheses that enclose the subfield, such as: 

keyword ( iteml item2 item3) 

where iteml, item2, and item3 are members of a list. 

If a subfield has as its first parameter a positional parameter that may be entered 
as a list and there are additional parameters in the subfield, a separate set of 
parentheses is required to enclose the list, such as: 

keyword (( iteml item2 item3) param) 

where iteml, item2, and item3 are members of a list, and param is a parameter 
not included in the list. 
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Using the Parse Macro Instructions to Define Command Syntax 



A command processor using the parse service routine must build a parameter 
control list (PCL) defining the syntax of acceptable command parameters. Each 
acceptable command parameter is described by a parameter control entry (PCE) 
within the PCL. The parse service routine compares the command parameters 
within the command buffer against the PCL to determine if valid command 
parameters have been entered. 

Parse returns the results of this comparison to the command processor in a 
parameter descriptor list (PDL). The PDL is composed of separate entries 
(PDEs) for each of the command parameters found in the command buffer. 

The command processor builds the PCL and the PCEs within it using the parse 
macro instructions. These macro instructions generate the PCL and establish 
symbolic references for the PDL returned by the parse service routine. 

The parse macros that generate input to parse may be issued in a program loaded 
above 16 megabytes. The IKJRLSA macro may be issued in either 24- or 31 -bit 
addressing mode. If the PCL resides above 16 megabytes, once it has been passed 
to parse, the caller should not attempt to update it via a validity check exit. If 
the PCL resides below 1 6 megabytes, the caller may update the PCL via a validity 
check exit after passing it to parse. 

There are eleven parse macro instructions: 

• IKJPARM 

• IKJPOSIT 

• IKJTERM 

• IKJOPER 

• IKJRSVWD 

• IKJIDENT 

• IKJKEYWD 

• IKJNAME 

• IKJSUBF 

• IKJENDP 

• IKJRLSA 

These macro instructions perform the following functions: 

1. When complete, all of the parse macros, except for IKJRLSA, return to the 
user's CSECT. If a DSECT appears between the CSECT statement and the 
parse macro(s), an assembly error occurs. To prevent this error, place the 
DSECT after the macro(s). 

2. The IKJPARM macro instruction begins the PCL CSECT and the PDL 
DSECT, and provides symbolic addresses for both. 

3. The IKJPOSIT, IKJTERM, IKJOPER, IKJRSVWD, IKJIDENT, 
IKJKEYWD, IKJNAME, and IKJSUBF macro instructions describe the 
positional and keyword parameters valid for the command processor. These 
macro instructions expand into the PCEs required by the parse service routine 
during its scan of the command buffer. The label fields of these macro 
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instructions are used as labels within the DSECT that maps the PDL returned 
by the parse service routine. 

4. The IKJENDP macro instruction ends the PCL CSECT. 

5. The IKJRLSA macro instruction releases the virtual storage obtained by the 
parse service routine for the PDL. 



IKJPARM - Beginning the PCL and the PDL 



Code the IKJPARM macro instruction to begin the parameter control list and to 
provide a symbolic address for the beginning of the parameter descriptor list 
returned by the parse service routine. The PCL is constructed in the CSECT 
named by the label field of the macro instruction; the PDL will be mapped by the 
DSECT named in the DSECT operand of the macro instruction. 

Figure 15-13 shows the format of the IKJPARM macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



label 


IKJPARM 


DSECT= (dsect name) 
| IKJPARMD j 



Figure 15-13. The IKJPARM Macro Instruction 

label 

The name you provide is used as the name of the CSECT in which the PCL 
is constructed. 

DSECT = 

Provides a name for the DSECT created to map the parameter descriptor 
list. This may be any name; the default is IKJPARMD. 

The Parameter Control Entry Built By IKJPARM: The IKJPARM macro 
instruction generates the parameter control entry (PCE) shown in Figure 15-14. 
This PCE begins the parameter control list. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 
2 

2 




Length of the parameter control list. This field contains a hexadecimal 
number representing the number of bytes in this PCL. 

Length of the parameter descriptor list. This field contains a 
hexadecimal number representing the number of bytes in the parameter 
descriptor list returned by the parse service routine. 

This field contains a hexadecimal number representing the offset within 
the PCL to the first IKJKEYWD PCE or to an end-of-field indicator if 
there are no keywords. An end-of-field indicator may be an IKJSUBF 
or an IKJENDP PCE. 



Figure 15-14. The Parameter Control Entry Built by IKJPARM 
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IKJPOSIT - Describing a Delimiter-Dependent Positional Parameter 



Code the IKJPOSIT macro instruction to describe most of the 
delimiter-dependent positional parameters. IKJIDENT is used to describe the 
others. 

The order in which you code the macros for positional parameters is the order in 
which the parse service routine expects to find the positional parameters in the 
command string. 

Figure 15-15 shows the format of the IKJPOSIT macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



label 



IKJPOSIT 



SPACE 

DELIMITER 

STRING 

VALUE 

ADDRESS [, EXTENDED] 

PSTRING 

USERID 

UID2PSWD 

DSNAME 

DSTHING 

QSTRING 

JOBNAME 



[ ,LIST] [ , RANGE] 



[ ,VOLSER] [ ,DDNAM] [ ,USID] 



[ ,SQSTRING] 

P UPPERCASE ,PROMPT=' prompt data' 1 
[,ASIS ,DEFAULT=' default value j 

[,HELP=( 'help data 1 ,* help data',...)] 

[ ,VALIDCK=symbolic-address] 



Figure 15-15. The IKJPOSIT Macro Instruction 



label 



This name is used as the symbolic address within the PDL DSECT of the 
parameter descriptor entry for the parameter described by this IKJPOSIT 
macro instruction. 

These are the positional parameter types recognized by the parse service 
routine. A syntactic definition of each is provided in "Delimiter-Dependent 
Parameters" earlier in this section. 

SPACE 

DELIMITER 

STRING 

VALUE 

ADDRESS 

PSTRING 

USERID 

UID2PSWD 

DSNAME 

DSTHING 

QSTRING 

JOBNAME 



1 5-32 TSO/E Guide to Writing a TMP or a CP 



SQSTRING 

The command operand is processed either as a string or as a quoted string. 
If the delimiter is an apostrophe, the command operand is processed as a 
quoted string. If the delimiter is any of the other acceptable delimiter 
characters, the command operand is processed as a string. The SQSTRING 
option can only be specified if STRING is specified for the parameter type. 
As an example, if SQSTRING is coded in the IKJPOSIT macro instruction, 
a terminal user entering a command could specify either: 

/string/string. . . 

or 

'string' 'string' ... 

EXTENDED 

Specifies that the user may enter 31 -bit addresses. This operand is valid 
only with ADDRESS. For more information, refer to the descriptions of 
absolute, relative, and indirect addresses and address expression under the 
description of the address parameter. 

LIST 

The command operands may be entered by the terminal user as a list: 

commandname (parameter parameter , . . . ) 

This list option may be used with the following delimiter-dependent 
positional parameters: 

USERID, DSNAME, DSTHING, ADDRESS, VALUE, JOBNAME, 
and PSTRING (in subfield only). 

RANGE 

The command operands may be entered by the terminal user as a range: 

commandname parameter rparameter 

This range option may be used with the following delimiter-dependent 
positional parameters: 

ADDRESS 
VALUE 

VOLSER 

Specifies that a data set name is to be a volume serial name. This operand 
is valid only with DSNAME or DSTHING. If the first character is 
numeric, a maximum of six characters are allowed. 

DDNAM 

Specifies a data definition name. This option causes an INVALID 
DDNAME message if the name is invalid. 
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USID 

Specifies that the user identification is to prefix all data set names that 
either are not entered in quotes or start with an asterisk. If you specify 
USID and DSTHING and the first character of a data set name is an 
asterisk (*), the parse service routine does not prefix the user ID. 

Note: The following options (UPPERCASE, ASIS, PROMPT, 
DEFAULT, HELP, and VALIDCK) may be used with all 
delimiter-dependent positional parameters except SPACE and 
DELIMITER. 

UPPERCASE 

The parameter is to be translated to uppercase. 

ASIS 

The parameter is to be left as it was entered by the terminal user. 

PROMPT = 'prompt data' 

The parameter described by this IKJPOSIT macro instruction is required; 
the prompting data is the message to be issued if the parameter is not 
entered by the terminal user. If prompting is necessary and the terminal is 
in prompt mode, the parse service routine adds a message-identifying 
number (message ID) and the word ENTER to the beginning of this 
message before writing it to the terminal. If prompting is necessary but the 
terminal is in no-prompt mode, the parse service routine adds a message ID 
and the word MISSING to the beginning of this message before writing it 
to the terminal. 

DEFAULT = 'default value' 

The parameter described by this IKJPOSIT macro instruction is required, 
but the terminal user need not enter it. If the parameter is not entered, the 
value specified as the default value is used. 

Note: If neither PROMPT nor DEFAULT is specified, the parameter is 
optional. The parse service routine takes no action if the parameter 
specified by this IKJPOSIT macro instruction is not present in the 
command buffer. 

HELP = ('help data','help data'...) 

You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas. These messages 
are issued one at a time after each question mark is entered by the terminal 
user in response to a prompting message from the parse service routine. 
These messages are not sent to the user when the prompt is for a password 
on a dsname or userid parameter. 

Parse adds a message ID and the word ENTER (in prompt mode) or 
MISSING (in no-prompt mode) to the beginning of each message before 
writing it to the terminal. 

VALIDCK = symbolic-address 

Supply the symbolic address of a validity checking subroutine if you want to 
perform additional validity checking on this parameter. Parse calls this 
routine after first determining that the parameter is syntactically correct. 
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The Parameter Control Entry Built by IKJPOSIT: The IKJPOSIT macro 
instruction generates the variable length parameter control entry (PCE) shown in 
Figure 15-16. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 




Flags. These flags are set to indicate which options were specified in the 
IKJPOSIT macro instruction. 




Byte 1 
001 


This is an IKJPOSIT PCE. 




...1 .... 


PROMPT 




.... 1... 


DEFAULT 




1.. 


This is an extended format PCE. If the VALIDCK parameter was 
specified, the length of the field containing the address of the validity 
checking routine is four bytes. 




1. 


HELP 




1 


VALIDCK 




Byte 2 

1 

.1 

..1 

.... 1... 

1.. 

1. 

1 


LIST 

ASIS 

RANGE 

SQSTRING 

USID 

VOLSER 

DDNAME 


2 




Length of the parameter control entry. This field contains a 
hexadecimal number representing the number of bytes in this IKJPOSIT 
PCE. 


2 




Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the related parameter descriptor entry built by the 
parse service routine. 


1 




This field contains a hexadecimal number indicating the type of 
positional parameter described by this PCE. These numbers have the 
following meaning: 

HEX 

1 DELIMITER 

2 STRING 

3 VALUE 

4 ADDRESS 

5 PSTRING 

6 USERID 

7 DSNAME 

8 DSTHING 

9 QSTRING 
A SPACE 

B JOBNAME 

C UID2PSWD 

D EXTENDED ADDRESS 

E to FF Not used. 


1 




Contains the length minus one of the default or 
prompting information supplied on the 
IKJPOSIT macro instruction. This field and the 
next are present only if DEFAULT or PROMPT 
was specified on the IKJPOSIT macro instruction. 


Variable 




This field contains the prompting or default 

information supplied on the IKJPOSIT macro instruction. 



Figure 15-16 (Part 1 of 2). The Parameter Control Entry Built by IKJPOSIT 
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Number 
of Bytes 


Field 


Contents or Meaning 


2 

1 

2 

2 
Variable 

3 or 4 




This field contains a hexadecimal figure representing the length in bytes 
of all the PCE fields used for second level messages. The figure includes 
the length of this field. The fields are present only if HELP is specified 
on the IKJPOSIT macro instruction. 

This field contains a hexadecimal number representing the number of 
second level messages specified by HELP on this IKJPOSIT PCE. 

This field contains a hexadecimal number representing the length of this 
HELP segment. The length figure includes the length of this field, the 
message segment offset field, and the length of the information. These 
fields are repeated for each second level message specified by HELP on 
the IKJPOSIT macro instruction. 

This field contains the message segment offset. It is set to X'0000'. 

This field contains one second level message supplied on the IKJPOSIT 
macro instruction specified by HELP. This field and the two preceding 
ones are repeated for each second level message supplied on the 
IKJPOSIT macro instruction. These fields do not appear if second level 
message data was not supplied. 

This field contains the address of a validity checking routine if 
VALIDCK was specified on the IKJPOSIT macro. If the "extended 
format PCE" bit is on in the IKJPOSIT PCE, the address is four bytes 
long; if the bit is off, the address is three bytes long. This field is not 
present if VALIDCK was not specified. 



Figure 15-16 (Part 2 of 2). The Parameter Control Entry Built by IKJPOSIT 



IKJTERM - Describing a Delimiter-Dependent Positional Parameter 



Code the IKJTERM macro instruction to describe a positional parameter that is 
one of the following: 

• Statement number 

• Constant 

• Variable 

• Constant or variable 

The order in which you code the macros for positional parameters is the order in 
which the parse service routine expects to find the parameters in the command 
string. 

Figure 15-17 shows the format of the IKJTERM macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



label 



IKJTERM 



'parameter-type' [,LIST] [, RANGE] 

T UPPERCASE] f" /STMT 

LaSIS J ,TYPE=JCNST 

iVAR 

VANY 

[,SBSCRPT[=label-PCE] ] HprOMPT^ prompt data 

|_,DEFAULT=' default valu 

[ , HELP= ( ' help data • , • help data ',...)] 

[ ,VALIDCK=symbolic-address] [ ,RSVWD=label-PCE] 



Lue j 



Figure 15-17. The IKJTERM Macro Instruction 
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label 

This name is used to address the PCE built by the IKJTERM macro. The 
hexadecimal offset to the parameter descriptor entry described by this 
IKJTERM macro instruction is contained in the PCE. 

Note: The hexadecimal offset to the PDE will contain binary zero when the 
IKJTERM macro is describing a subscript of a data name. 

'parameter-type' 

This field is required so that the parameter can be identified when an error 
message is necessary. This field differs from the PROMPT field in that the 
PROMPT field is not required and, if supplied, is used only for a required 
parameter that is not entered by the terminal user. Blanks within the 
apostrophes are allowed. 

LIST 

The command operands may be entered by the terminal user as a list, in 
the form: 

commandname (parameter , parameter , . . . ) 

The LIST option may be used with any of the TYPE = positional 
parameters. 

RANGE 

The command operands may be entered by the terminal user as a range, in 
the form: 

commandname parameter rparameter 

The RANGE option may be used with any of the TYPE = positional 
parameters. 

Note: The LIST and RANGE options can not be used when the 
IKJTERM macro instruction is describing a subscript of a data-name. 

UPPERCASE 

The parameter is to be translated to uppercase. 

ASIS 

The parameter is to be left as it was entered by the terminal user. 

TYPE = 

Describes the type of the parameter as one of: 

• STMT - statement number 

• CNST - constant 

• VAR - variable 

• ANY - constant or variable 

Note: A syntactical definition of these parameters is contained under 
"Delimiter-Dependent Parameters." 
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SBSCRIPT[ = label-PCEJ 

Specifies one of two conditions: 

1. If SBSCRIPT is entered with a label-PCE then the data-name described 
by the IKJTERM macro may be subscripted. Supply the name of the 
label of an IKJTERM macro instruction that describes the subscript. 
Only TYPE = VAR or TYPE = ANY parameters can be subscripted. 

2. If SBSCRPT is entered without a label-PCE then the IKJTERM macro 
is describing the subscript of a data-name. All TYPE = parameters may 
be used on a subscript except TYPE = STMT. The LIST and RANGE 
options can not be used on an IKJTERM macro that is describing a 
subscript. 

Note: Two IKJTERM macros are coded to describe a subscripted 
data-name. The first IKJTERM macro describes the data name and 
specifies the SBSCRIPT option with the label of the second IKJTERM 
macro. The second IKJTERM macro describes the subscript of the 
data-name and specifies SBSCRPT without a label-PCE. The second macro 
must immediately follow the first. 

PROMPT = 'prompt data' 

The parameter described by this IKJTERM macro instruction is required. 
The prompting data is the message to be issued if the parameter is not 
entered by the terminal user. If prompting is necessary and the terminal is 
in prompt mode, the parse service routine adds a message-identifying 
number (message ID) and the word ENTER to the beginning of the message 
before writing it to the terminal. 

If prompting is necessary but the terminal is in no-prompt mode, the parse 
service routine adds a message ID and the word MISSING to the beginning 
of the message before writing it to the terminal. If a subscripted data-name 
requires prompting, the terminal user is prompted for the entire name 
including the subscript. 

DEFAULT = 'default value' 

The parameter described by this IKJTERM macro instruction is required, 
but the terminal user need not enter it. If the parameter is not entered, the 
value specified as the default value is used. 

Note: If neither PROMPT nor DEFAULT is specified, the parameter is 
optional. The parse service routine takes no action if the parameter is not 
present. 

HELP - ('help dataVhelp data',...) 

You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas. These messages 
are issued one at a time after each question mark entered by the terminal 
user in response to a prompting message from the parse service routine. 

Parse adds a message ID and the word ENTER (in prompt mode) or 
MISSING (in no-prompt mode) to the beginning of each message before 
writing it to the terminal. 
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V ALIDCK = symbolic-address 

Supply the symbolic address of a validity checking subroutine if you want to 
perform additional checking on this parameter. Parse calls this routine after 
first determining that the parameter is syntactically correct. 

RSVWD = label-PCE 

This parameter is used when TYPE = CNST or TYPE = ANY is specified. 
This option indicates that this parameter can be a figurative constant. 
Supply the address of the PCE (label on a IKJRSVWD macro instruction) 
that begins the list of reserved words that can be entered as a figurative 
constant. 

This list of reserved words is defined by a series of IKJNAME macros that 
contain all possible names and immediately follow the IKJRSVWD macro. 

Note: The IKJRSVWD macro can be coded anywhere in the list of macros 
that build the PCL except following an IKJSUBF macro instruction. This 
permits other IKJTERM macro instructions to refer to the same list. 

The Parameter Control Entry Built by IKJTERM: The IKJTERM macro 
instruction generates the variable parameter control entry (PCE) shown in 
Figure 15-18. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 




Flags. These flags are set to indicate options on the IKJTERM macro 
instruction. 




Byte 1 
110 


This is an IKJTERM PCE. 




...1 .... 


PROMPT 




.... 1... 


DEFAULT 




1.. 


This is an extended format PCE. If the VALIDCK parameter was 
specified, the length of the field containing the address of the validity 
checking routine is four bytes. 




1. 


HELP 




1 


VALIDCK 




Byte 2 

1 

.1 

..1 

...1 .... 
.... 1... 
000 


LIST 

ASIS 

RANGE 

This term may be SUBSCRIPTED. 

A reserved word PCE is chained from this term. 

Reserved 


2 




The hexadecimal length of this PCE. 


2 




Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the parameter descriptor entry built by the parse 
routine. 


1 




This field indicates the type of positional parameter described by this 
PCE. 




1 

.1 

..1 

...1 .... 
.... 1... 
000 


STATEMENT NUMBER 

VARIABLE 

CONSTANT 

ANY (constant or variable) 
This term is a SUBSCRIPT term. 
Reserved 



Figure 15-18 (Part 1 of 2). The Parameter Control Entry Built by IKJTERM 
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Number 
of Bytes 


Field 


Contents or Meaning 


4 

Variable 
1 

Variable 

2 
2 
2 
1 

2 

2 
Variable 

3 or 4 


Byte 1-2 
Byte 3-4 


Contains the hexadecimal length of the parameter- type field. 

Contains the offset of the parameter- type field. It is set to X'0012'. 

Contains the parameter-type field. 

Contains the length of the default or prompting information supplied on 
the macro instruction. 

Contains the default or prompting information supplied on the macro 
instruction. 

If a subscript is specified on the macro, this field contains the offset into 
the parameter control list of the subscript PCE. 

If a reserved word PCE is specified on the macro, this field contains the 
offset into the parameter control list of the reserved word PCE. 

Contains the length (including this field) of all the PCE fields used for 
second level messages if HELP is specified on the macro. 

The number of second level messages specified on the macro instruction 
by the HELP parameter. 

Contains the length of this segment including this field, the message 
offset field and second level message. 

Note: This field and the following two are repeated for each second 
level message specified by HELP on the macro. 

This field contains the message segment offset. 

This field contains one second level message specified by HELP on the 
macro instruction. This field and the two preceding fields are repeated 
for each second level message specified. 

This field contains the address of a validity checking routine if 
VALIDCK was specified on the IKJTERM macro. If the "extended 
format PCE" bit is on in the IKJTERM PCE, the address is four bytes 
long; if the bit is off, the address is three bytes long. This field is not 
present if VALIDCK was not specified. 



Figure 15-18 (Part 2 of 2). The Parameter Control Entry Built by IKJTERM 



IK JOPER - Describing a Delimiter-Dependent Positional Parameter 



Code the IKJOPER macro instruction to provide a parameter control entry 
(PCE) that describes an expression. An expression consists of three parts; two 
operands and one operator in the form: 

(operandi operator operand2 ) 

typically entered as: 

(abc eq 123) 

The parts of an expression are described by PCEs that are chained to the 
IKJOPER PCE. The IKJTERM macro instruction is used to identify the 
operands, and the IKJRSVWD macro instruction is used to identify the operator. 
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Figure 15-19 shows the format of the IKJOPER macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



label 


IKJOPER 


'parameter-type' nPROMPT= 'prompt data' ~| 
1, DEFAULT= ' default value j 

[ ,HELP=( 'help data', 'help data',...)] 

[ ,VALIDCK=symbolic-address] ,OPERNDl=labell 

,OPERND2=label2 ,RSVWD=label3 

[ ,CHAIN=label4] 



Figure 15-19. The IKJOPER Macro Instruction 

label 

This name is used to address the PCE built by the IKJOPER macro. The 
hexadecimal offset to the parameter descriptor entry described by this macro 
is contained in the PCE. 

'parameter-type' 

This field is required so that the parameter can be identified when an error 
message is necessary. This field differs from the PROMPT field in that the 
PROMPT field is not required and if supplied is used only for a required 
parameter that is not entered by the terminal user. Blanks within the 
apostrophes are allowed. 

Note: This field is used only with error messages for the complete 
expression. The IKJTERM and IKJRSVWD PCEs are used with an error 
message for missing operands or operator. If a validity check routine 
specifies an invalid expression, then the entire expression is prompted for. 

PROMPT = 'prompt data' 

The parameter described by this IKJOPER macro instruction is required. 
The prompting data is the message to be issued if the parameter is not 
entered by the terminal user. If prompting is necessary and the terminal is 
in prompt mode, the parse service routine adds a message-identifying 
number (message ID) and the word ENTER to the beginning of the message 
before writing it to the terminal. If prompting is necessary but the terminal 
is in no-prompt mode, the parse service routine adds a message ID and the 
word MISSING to the beginning of the message before writing it to the 
terminal. 

DEFAULT = 'default value' 

The parameter described by this IKJOPER macro instruction is required, 
but the terminal user need not enter it. If the parameter is not entered the 
value specified as the default value is used. 

Note: If neither PROMPT nor DEFAULT is specified, the parameter is 
optional. The parse service routine takes no action if the parameter is not 
present. 
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HELP = ('help dataVhelp data',...) 

You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas. These messages 
are issued one at a time after each question mark entered by the terminal 
user in response to a prompting message from the parse service routine. 

Parse adds a message ID and the word ENTER (in prompt mode) or 
MISSING (in no-prompt mode) to the beginning of each message before 
writing it to the terminal. 

VALIDCK = symbolic-address 

Supply the symbolic address of a validity checking subroutine if you want to 
perform additional checking on this expression. The parse service routine 
calls this routine after first determining that the expression is syntactically 
correct. 

OPERNDl=labell 

Supply the name of the label field of the IKJTERM macro instruction that 
is used to describe the first operand in the expression. This IKJTERM 
macro instruction should be coded immediately following the IKJOPER 
macro instruction that describes the expression. 

OPERND2 = label2 

Supply the name of the label field of the IKJTERM macro instruction that 
is used to describe the second operand in the expression. This IKJTERM 
macro instruction should be coded immediately following the IKJNAME 
macro instructions that describe the operator in the expression under the 
associated IKJRSVWD macro instruction. 

RSVWD = labeI3 

Supply the name of the label field of the IKJRSVWD macro instruction 
that begins the list of reserved words that are used to describe the possible 
operators to be entered for the expression. The IKJRSVWD and associated 
IKJNAME macro instructions should be coded immediately following the 
IKJTERM macro that describes the first operand, and immediately 
preceding the IKJTERM macro that describes the second operand. 

CHAIN = label4 

Indicates that this parameter described by the IKJOPER macro instruction 
may be entered as an expression or as a variable. Supply the name of the 
label field of an IKJTERM macro instruction that describes the variable 
term. The LIST and RANGE options are not permitted on this IKJTERM 
macro instruction. Code this IKJTERM macro instruction immediately 
following the IKJTERM macro that describes the second operand. 

Note: The parse service routine first determines if the parameter is entered 
as an expression. If the parameter is an expression, that is, enclosed in 
parentheses, then it is processed as an expression. If it is not an expression, 
then it is processed using the chained IKJTERM PCE to control the scan of 
the parameter. 
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The Parameter Control Entry Built by IKJOPER: The IKJOPER macro 
instruction generates the variable parameter control entry (PCE) shown in 
Figure 15-20. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 




Flags. These flags are set to indicate options on the IKJOPER macro 
instruction. 




Byte 1 
111 

...1 .... 


This is an IKJOPER PCE. 
PROMPT 




.... 1... 


DEFAULT 




1.. 


This is an extended format PCE. If the VALIDCK parameter is 
specified, the length of the field containing the address of the validity 
checking routine is four bytes. 




1. 


HELP 




1 


VALIDCK 




Byte 2 
0000 0000 


Reserved 


2 




The hexadecimal length of this PCE. 


2 




Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the parameter descriptor entry built by the parse 
service routine. 


4 


Byte 1-2 


Contains the hexadecimal length of the parameter-type field. 




Byte 3-4 


Contains the offset of the parameter-type field (X'0012'). 


Variable 




Contains the parameter-type field. 


2 




If a reserved word PCE is specified on the macro, this field contains the 
offset into the parameter control list of the reserved word PCE. 


2 




Contains the offset into the parameter control list of the OPERND1 
PCE. 


2 




Contains the offset into the parameter control list of the OPERND2 
PCE. 


2 




Contains the offset into the parameter control list of the chained term 
PCE if present. Zero if not present. 


1 




Contains the length of the default or prompting information supplied on 
the macro instruction. 


Variable 




Contains the default or prompting information supplied on the macro 
instruction. 


2 




Contains the length (including this field) of all the PCE fields used for 
second level messages if HELP is specified on the macro. 


1 




The number of second level messages specified on the macro instruction 
by the HELP = parameter. 


2 




Contains the length of this segment including this field, the message 
offset field and second level message. 

Note: This field and the following two are repeated for each second 
level message specified by HELP on the macro. 


2 




This field contains the message segment offset. 


Variable 




This field contains one second level message specified by HELP on the 
macro instruction. This field and the two preceding fields are repeated 
for each second level message specified. 


3 or 4 




This field contains the address of a validity checking routine if 
VALIDCK was specified on the IKJOPER macro. If the "extended 
format PCE" bit is on in the IKJOPER PCE, the address is four bytes 
long; if the bit is off, the address is three bytes long. This field is not 
present if VALIDCK was not specified. 



Figure 15-20. The Parameter Control Entry Built by IKJOPER 
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IKJRSVWD - Describing a Delimiter-Dependent Positional Parameter 



Code the IKJRSVWD macro instruction with at least the 'parameter-type' 
operand when you use it: 

• With the RSVWD keyword of the IKJOPER macro instruction to define the 
beginning of a list of the possible reserved words that can be an operator in 
an expression. The possible reserved words that can be operators in an 
expression are identified by a list of IKJNAME macro instructions that 
immediately follow the IKJRSVWD macro instruction. 

• By itself to define a positional reserved word. 

Code the IKJRSVWD macro instruction without operands when you use it: 

• With the RSVWD keyword of the IKJTERM macro instruction to define the 
beginning of a list of possible reserved words that can be used as a figurative 
constant. The possible figurative constants are defined by a list of IKJNAME 
macros that immediately follow the IKJRSVWD macro instruction. 

In this case, simply code the IKJRSVWD macro instruction as: 



label 



IKJRSVWD 



The order in which you code the macros for positional parameters is the order in 
which the parse service routine expects to find the parameters in the command 
string. 

Figure 15-21 shows the format of the IKJRSVWD macro instruction. Each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



label 


IKJRSVWD 


'parameter-type' TPROMPT= 'prompt data' ~J 
LdeFAULT=' default value J 

[,HELP=( 'help data', 'help data',...)] 



Figure 15-21. The IKJRSVWD Macro Instruction 



label 



This name is used to address the PCE built by the IKJRSVWD macro. The 
hexadecimal offset to the parameter descriptor entry described by this macro 
is contained in the PCE. 

Note: The following operands are not coded on the IKJRSVWD macro 
when you use it with the RSVWD keyword of the IKJTERM macro 
instruction. 
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'parameter-type' 

This field is required so that the parameter can be identified when an error 
message is necessary. This field differs from the PROMPT field in that the 
PROMPT field is not required and if supplied is used only for a required 
parameter that is not entered by the terminal user. Blanks within the 
apostrophes are allowed. 

PROMPT = 'prompt data' 

The parameter described by this IKJRSVWD macro instruction is required. 
The prompting data is the message to be issued if the parameter is not 
entered by the terminal user. If prompting is necessary and the terminal is 
in prompt mode, parse adds a message-identifying number (message ID) and 
the word ENTER to the beginning of the message before writing it to the 
terminal. If prompting is necessary but the terminal is in no-prompt mode, 
parse adds a message ID and the word MISSING to the beginning of the 
message before writing it to the terminal. 

DEFAULT = 'default value' 

The parameter described by this IKJRSVWD macro instruction is required, 
but the terminal user need not enter it. If the parameter is not entered, the 
value specified as the default value is used. 

Note: If neither PROMPT nor DEFAULT is specified, the parameter is 
optional. The parse service routine takes no action if the parameter is not 
present. 

HELP = ('help data','help data',...) 

You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas. These messages 
are issued one at a time after each question mark entered by the terminal 
user in response to a prompting message from the parse routine. 

The parse service routine adds a message ID and the word ENTER (in 
prompt mode) or MISSING (in no-prompt mode) to the beginning of each 
message before writing it to the terminal. 
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The Parameter Control Entry Built by IKJRSVWD: The IKJRSVWD macro 
instruction generates the variable parameter control entry (PCE) shown in 
Figure 15-22. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 




Flags. These flags are set to indicate options on the IKJRSVWD macro 
instruction. 




Byte 1 
101. ... 
...1 .... 
.... 1... 

0.. 

1. 




This is an IKJRSVWD PCE. 

PROMPT 

DEFAULT 

Reserved 

HELP 

Reserved 




Byte 2 
1 


This PCE is used with the IKJTERM macro as a figurative constant. 







This PCE is not used with the IKJTERM macro as a figurative 
constant. 




.000 0000 


Reserved. 


2 




The hexadecimal length of this PCE. 


2 




Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the parameter descriptor entry built by the parse 
service routine. 

Note: The following fields are omitted if this PCE is used with the 
IKJTERM macro to describe a figurative constant. 


4 


Byte 1-2 


Contains the hexadecimal length of the parameter-type field. 




Byte 3-4 


Contains the offset of the parameter-type field (X'0012'). 


Variable 




Contains the parameter-type field. 


1 




Contains the length of the default or prompting information supplied on 
the macro instruction. 


Variable 




Contains the default or prompting information supplied on the macro 
instruction. 


2 
1 




Contains the length (including this field) of all the PCE fields used for 
second level messages if HELP is specified on the macro. 

The number of second level messages specified on the macro instruction 
by the HELP = parameter. 


2 




Contains the length of this segment including this field, the message 
offset field and second level message. 

Note: This field and the following two are repeated for each second 
level message specified by HELP on the macro. 


2 




This field contains the message segment offset. 


Variable 




This field contains one second level message specified by HELP on the 
macro instruction. This field and the two preceding fields are repeated 
for each second level message specified. 



Figure 15-22. The Parameter Control Entry Built by IKJRSVWD 



IK JIDENT - Describing a Non-Delimiter-Dependent Positional Parameter 

Execute the IKJIDENT macro instruction to describe a positional parameter that 
does not depend upon a particular delimiter for its syntactical definition — those 
parameters discussed under "Positional Parameters Not Dependent on 
Delimiters." 

These positional parameters must be in the form of a character string, with 
restrictions on the beginning character, additional characters, and length, decimal 
integers, or hexadecimal characters. 
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The order in which you code the macro instructions for positional parameters is 
the order in which the parse service routine expects to find the positional 
parameters in the command string. 

Figure 15-23 shows the format of the IKJIDENT macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



label 



IKJIDENT 



'parameter-type' [,LIST] [, RANGE] [,PTBYPS] 
[, ASTERISK] f, UPPERCASE" ! [ ,MAXLNTH=number ] 



[*, uppercase" ) [ ,] 

[,ASIS J 



, FIRST= 



,ASIS 

ALPHA 

NUMERIC 

ALPHANUM 

ANY 

NONATABC 

NONATNUM IJ 



, OTHER= 



' ALPHA 
.NUMERIC 
I ALPHANUM 
(ANY 

NONATABC 
NONATNUM 



,PROMPT=' prompt data' 
,DEFAULT=' default value 

',CHAR ' 

, INTEG 

|_,HEX J 

[ ,VALIDCK=symbolic-address] 

[,HELP=( 'help data', 'help data',...)] 



Figure 15-23. The IKJIDENT Macro Instruction 



label 



This name is used within the PDL DSECT as the symbolic address of the 
parameter descriptor entry for this positional parameter. 



'parameter-type' 

This field is required so that the parameter can be identified when an error 
message is necessary. This field differs from the PROMPT field in that the 
PROMPT field is not required and if supplied is used only for a required 
parameter that is not entered by the terminal user. Blanks within the 
apostrophes are allowed. 

LIST 

This positional parameter may be entered by the terminal user as a list, that 
is, in the form: 

commandname (parameter , parameter ,... ) 

RANGE 

This positional parameter may be entered by the terminal user as a range, 
that is, in the form: 

commandname parameter :parameter 

If you specify RANGE and OTHER = ANY, parse treats any colons it finds 
as delimiters. For example, the first colon after RANGE marks the end of 
the first part of the range and the start of the next part of the range. To 
include the colon in your data, you must use the CHAR operand and 
enclose the colon by quotation marks. 
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PTBYPS 

All prompting for the parameter is to be done in print inhibit mode. This 
option may be specified only when the PROMPT option is specified. 

ASTERISK 

An asterisk may be substituted for this positional parameter. 

Note: ASTERISK and INTEGER are mutually exclusive. 

UPPERCASE 

The parameter is to be translated to uppercase. 

ASIS 

The parameter is to be left as it was entered. 

MAXLNTH = number 

The maximum number of characters the string may contain. If you do not 
code the MAXLNTH operand, the parse service routine accepts a character 
string of any length. 

FIRST = 

Specify the character type restriction on the first character of the string. 

OTHER = 

Specify the character type restriction on the characters of the string other 
than the first character. 

Note: The restrictions on the characters of the string are specified by 
coding one of the following character types after the FIRST = and the 
OTHER = operands. This is true unless HEX, INTEG, or CHAR is 
specified. FIRST = and OTHER = serve no purpose in these cases. 

ALPHA 

An alphabetic or national character. ALPHA is the default value for both 
the FIRST and the OTHER operands. 

NUMERIC 

A digit, 0-9. 

ALPHANUM 

An alphabetic, numeric, or national character. 

ANY 

Any character other than a blank, comma, tab, or semicolon. Parentheses 
must be balanced. 

NONATABC 

An alphabetic character only. National characters and numerics are 
excluded. 
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NONATNUM 

An alphabetic or numeric character. National characters are excluded. 

PROMPT = 'prompt data' 

The parameter is required; the prompting data is the message to be issued if 
the parameter is not entered by the terminal user. If prompting is necessary 
and the terminal is in prompt mode, the parse service routine adds a 
message-identifying number (message ID) and the word ENTER to the 
beginning of this message before writing it to the terminal. If prompting is 
necessary but the terminal is in no-prompt mode, the parse service routine 
adds a message ID and the word MISSING to the beginning of this message 
before writing it to the terminal. 

DEFAULT = 'default value' 

The parameter is required, but a default value may be used. If the 
parameter is not entered by the terminal user, the value specified as the 
default value is used. 

Note: The parameter is optional if neither PROMPT nor DEFAULT is 
specified. The parse service routine takes no action if the parameter 
specified by this IKJIDENT macro instruction is not present in the 
command buffer. 

CHAR 

Specifies that the parse service routine is to accept a string of characters as 
input. This input string may be either quoted or unquoted. 

INTEG 

Specifies that the parse service routine is to accept a numeric quantity as 
input. This quantity may be decimal, hexadecimal, or binary. The number 
is stored internally as a fullword binary value, regardless of how INTEG 
was specified. 

Note: A maximum length is automatically implied if the INTEG option is 
specified. For binary input, the maximum number of characters is 32. For 
hexadecimal input, the maximum length is 8. For decimal input, the 
maximum length is 10. 

HEX 

Specifies that the parse service routine is to accept a hexadecimal value as 
input. This string quantity may be hexadecimal or a quoted or non-quoted 
string. 

Note: All input entered in the form X'n...' must be valid hexadecimal digits 
(0-9, A-F). All input entered in the form B'n...' must be valid binary digits 
(0,1). All input entered as unquoted decimals must be valid decimal digits 
(0-9). 

VALIDCK = symbolic-address 

Supply the symbolic address of a validity checking subroutine if you want to 
perform additional validity checking on this parameter. The parse service 
routine calls the addressed routine after first determining that the parameter 
is syntactically correct. 
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HELP = ('help dataYhelp data'...) 

You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas. These messages 
are issued one at a time after each question mark entered by the terminal 
user in response to a prompting message from the parse service routine. 
These messages are not sent to the user when the prompt is for a password 
on a dsname or userid parameter. 

The parse service routine adds a message ID and the word ENTER (in 
prompt mode) or MISSING (in no-prompt mode) to the beginning of each 
message before writing it to the terminal. 

The Parameter Control Entry Built by IKJIDENT: The IKJIDENT macro 
instruction generates the variable length parameter control entry (PCE) shown in 
Figure 15-24. 
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Number 
of Bytes 


Field 


Contents or Meaning 


2 




Flags. These flags are set to indicate which options were specified in the 
IKJIDENT macro instruction. 




Byte 1 
100 


This is an IKJIDENT PCE. 




...1 .... 


PROMPT 




.... 1... 


DEFAULT 




1.. 


This is an extended format PCE. If the VALIDCK parameter is 
specified, the length of the field containing the address of the validity 
checking routine is four bytes. 




1. 

1 


HELP 
VALIDCK 




Byte 2 

1 

.1 

..1 

...0 0000 


LIST 
ASIS 
RANGE 

Reserved 


2 




Length of the parameter control entry. This field contains a 
hexadecimal number representing the number of bytes in this 
IKJIDENT PCE. 


2 




Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the related parameter descriptor entry built by the 
parse service routine. 


1 




A flag field indicating the options coded on the IKJIDENT macro 
instruction. 




1 

.1 

..1 

...1 .... 
.... 1... 

1.. 

00 


ASTERISK 
MAXLNTH 
PTBYPS 

Integer 
Character 
Hexadecimal 
Reserved 


1 




This field contains a hexadecimal number indicating the character type 
restriction on the first character of the character string described by the 
IKJIDENT macro instruction. 

HEX Acceptable characters: 

Any (except blank, comma, tab, semicolon) 

1 Alphabetic or national 

2 Numeric 

3 Alphabetic, national, or numeric 

4 Alphabetic 

5 Alphabetic or numeric 

6 to FF Not used 


1 




This field contains a hexadecimal number indicating the character type 
restriction on the other characters of the character string described by 
the IKJIDENT macro instruction. 

HEX Acceptable characters: 

Any (except blank, comma, tab, semicolon) 

1 Alphabetic or national 

2 Numeric 

3 Alphabetic, national, or numeric 

4 Alphabetic 

5 Alphabetic or numeric 

6 to FF Not used 



Figure 15-24 (Part 1 of 2). The Parameter Control Entry Built by IKJIDENT 
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Number 
of Bytes 



Field 



Contents or Meaning 



2 
Variable 

1 



Variable 

2 

1 

2 



Variable 



3 or 4 



This field contains a hexadecimal number representing the length of the 
parameter type segment. This figure includes the length of this field, the 
length of the message segment offset field, and the length of the 
parameter type field supplied on the IKJIDENT macro instruction. 

This field contains the message segment offset. It is set to X'0012'. 

This field contains the field supplied as the parameter type operand of 
the IKJIDENT macro instruction. 

This field contains a hexadecimal number representing the maximum 
number of characters the string may contain. This field is present only 
if the MAXLNTH operand was coded on the IKJIDENT macro 
instruction. 

This field contains the length minus one of the defaults or prompting 
information supplied on the IKJIDENT macro instruction. This field 
and the next are present only if DEFAULT or PROMPT were specified 
on the IKJIDENT macro instruction. 

This field contains the prompting or default information supplied on the 
IKJIDENT macro instruction. 

This field contains a hexadecimal figure representing the length in bytes 
of all the PCE fields used for second level messages. The figure includes 
the length of this field. The fields are present only if HELP is specified 
on the IKJIDENT macro instruction. 

This field contains a hexadecimal number representing the number of 
second level messages specified by HELP on this IKJIDENT PCE. 

This field contains a hexadecimal number representing the length of this 
HELP segment. The figure includes the length of this field, the message 
segment offset field, and the length of the information. These fields are 
repeated for each second level message specified by HELP on the 
IKJIDENT macro instruction. 

This field contains the message segment offset. It is set to X'0000'. 

This field contains one second level message supplied on the IKJIDENT 
macro instruction specified by HELP. This field and the two preceding 
ones are repeated for each second level message supplied on the 
IKJIDENT macro instruction; these fields do not appear if no second 
level message data was supplied. 

This field contains the address of a validity checking routine if 
VALIDCK was specified on the IKJIDENT macro. If the "extended 
format PCE" bit is on in the IKJIDENT PCE, the address is four bytes 
long; if the bit is off, the address is three bytes long. This field is not 
present if VALIDCK was not specified. 



Figure 15-24 (Part 2 of 2). The Parameter Control Entry Built by IKJIDENT 



IK JKEYWD - Describing a Keyword Parameter 



Execute the IKJKEYWD macro instruction to describe a keyword parameter. 
Execute a series of IKJNAME macro instructions to indicate the possible names 
for the keyword parameter. Keyword parameters may appear in any order in the 
command but must follow all positional parameters. A user is never required to 
enter a keyword parameter; if he does not, the default value you supply, if you 
choose to supply one, is used. Keywords may consist of any combination of 
alphameric characters up to 3 1 characters in length, the first of which must be an 
alphabetic character. 
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Figure 15-25 shows the format of the IKJKEYWD macro instruction. Each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



label 


IKJKEYWD 


[DEFAULT= ' default-value ' ] 



Figure 15-25. The IKJKEYWD Macro Instruction 



label 



This name is used within the PDL DSECT as the symbolic address of the 
parameter descriptor entry for this parameter. 

DEFAULT = 'default-value' 

The default value you specify is the value that is used if this keyword is not 
present in the command buffer. Specify the valid keyword names with 
IKJNAME macro instructions following this IKJKEYWD macro 
instruction. 

The Parameter Control Entry Built by IKJKEYWD: The IKJKEYWD macro 
instruction generates the variable length parameter control entry (PCE) shown in 
Figure 15-26. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 




Flags. These flags are set to indicate which options were coded in the 
IKJKEYWD macro instruction. 




Byte 1 

010 

...0 .... 
.... 1... 
000 


This is an IKJKEYWD PCE. 

Reserved. 

DEFAULT 

Reserved. 




Byte 2 
0000 0000 


Reserved. 


2 




Length of the parameter control entry. This field contains a 
hexadecimal number representing the number of bytes in this 
IKJKEYWD PCE. 


2 
1 




This field contains a hexadecimal offset from the beginning of the 
parameter descriptor list to the related parameter descriptor entry built 
by the parse service routine. 

This field contains the length minus one of the default information 
supplied on the IKJKEYWD macro instruction. This field and the next 
are present only if DEFAULT was specified on the IKJKEYWD macro 
instruction. 


Variable 




This field contains the default value supplied on the IKJKEYWD macro 
instruction. 



Figure 15-26. The Parameter Control Entry Built by IKJKEYWD 
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IKJNAME - Listing the Keyword or Reserved Word Parameter Names 



The IKJNAME macro instruction may be coded with the following two macro 
instructions: 

1. With the IKJKEYWD macro instruction to define keyword parameter names. 

2. With the IKJRSVWD macro instruction to define reserved word parameter 
names. 

A description and format of the IKJNAME macro instruction for both methods 
of coding follows: 

1. Code a series of IKJNAME macro instructions to indicate the possible names 
for a keyword parameter. One IKJNAME macro instruction is needed for 
each possible keyword name. Code the IKJNAME macro instructions 
immediately following the IKJKEYWD macro instruction to which they 
pertain. 

Figure 1 5-27 shows the format of the IKJNAME macro instruction. Each of 
the operands is explained following the figure. Appendix A describes the 
notation used to define macro instructions. 



IKJNAME 



'keyword-name' [ , SUBFLD=subf ie Id-name] 
[ , INSERT= ' keyword-string ' ] 
[ ALIAS= ( ' name • , * name ',...)] 



Figure 15-27. The IKJNAME Macro Instruction (when used with the IKJKEYWD 
Macro Instruction) 

keyword-name 

One of the valid keyword parameters for the IKJKEYWD macro 
instruction that precedes this IKJNAME macro instruction. 

SUBFLD = subfield-name 

This option indicates that this keyword name has other parameters 
associated with it. Use the subfield-name as the label field of the 
IKJSUBF macro instruction that begins the description of the possible 
parameters in the subfield. 

INSERT = 'keyword-string' 

The use of some keyword parameters may imply that other keyword 
parameters are required. The parse service routine inserts the keyword 
string specified into the command string just as if it had been entered as 
part of the original command string. The command buffer is not 
altered. 

ALIAS = ('name'/name',...) 

Specifies up to 32 alias names for a keyword. Each name represents a 
valid abbreviation or alternate name and must be enclosed in quotes. 
All abbreviations or names must be enclosed in a single set of 
parentheses. 
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2. Code a series of IKJNAME macro instructions to indicate the possible names 
for reserved words. One IKJNAME macro instruction is needed for each 
possible reserved word name. Code the IKJNAME macro instructions 
immediately following the IKJRSVWD macro instruction to which they 
apply. 

Figure 15-28 shows the format of the IKJNAME macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



IKJNAME 



'reserved-word name" 



Figure 15-28. The IKJNAME Macro Instruction (when used with the IKJRSVWD 
Macro Instruction) 

reserved-word name 

One of the valid reserved word parameters for the IKJRSVWD macro 
instruction that precedes the IKJNAME macro instructions. 

Note: The IKJNAME macro instruction has two uses when coded with the 
IKJRSVWD macro instruction. The reserved-words identified on the 
IKJNAME macros may be figurative constants when the IKJRSVWD 
macro is chained from an IKJTERM macro, or operators in an expression 
when the IKJRSVWD macro is chained from the IKJOPER macro. 

The Parameter Control Entry Built by IKJNAME: The IKJNAME macro 
instruction generates the variable length parameter control entry (PCE) shown in 
Figure 15-29. 

Note: Only the first four fields are valid when the IKJNAME macro instruction 
is coded with the IKJRSVWD macro instruction. 
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Number 
of Bytes 


Field 


Contents or Meaning 


2 




Flags. These flags are set to indicate which options were coded in the 
IKJNAME macro instruction. 




Byte 1 

Oil 

...0 0... 

1.. 

00 


This is an IKJNAME PCE. 

Reserved. 

SUBFLD 

Reserved. 




Byte 2 

000 

...1 .... 

1. 

.... 00.0 


Reserved. 
INSERT 
ALIAS 
Reserved. 


2 
1 




Length of the parameter control entry. This field contains a 
hexadecimal number representing the number of bytes in this 
IKJNAME PCE. 

This field contains the length minus one of the keyword or reserved 
word names specified on the IKJNAME macro instruction. 


Variable 




This field contains the keyword or reserved word name specified on the 
IKJNAME macro instruction. 


2 
1 




This field contains a hexadecimal offset, plus one, from the beginning of 
the parameter control list to the beginning of a subfield PCE. This field 
is present only if the SUBFLD operand was specified in the IKJNAME 
macro instruction. 

This field contains the length minus one of the keyword string included 
as the INSERT operand in the IKJNAME macro instruction. This field 
and the next are not present if INSERT was not specified. 


Variable 




This field contains the keyword string specified as the INSERT operand 
of the IKJNAME macro instruction. 


1 




The total number of aliases. 


1 




The length minus one of first alias. 


Variable 




The first alias. 


1 




The length minus one of second alias. 


Variable 




The second alias. 



Figure 15-29. The Parameter Control Entry Built by IKJNAME 



IKJSUBF - Describing a Keyword Subfield 



Keyword parameters may have subfields associated with them. A subfield 
consists of a parenthesized list of parameters directly following the keyword. 

Execute the IKJSUBF macro instruction to indicate the beginning of a subfield 
description. The IKJSUBF macro instruction ends the main part of the 
parameter control list or the previous subfield description, and begins a new 
subfield description. 

Note that the IKJSUBF macro instruction is used only to begin the subfield 
description; the subfield is described using the IKJPOSIT, IKJIDENT, and 
IKJKEYWD macro instructions, depending upon the type of parameters within 
the subfield. 

You must use the name you have coded as the SUBFLD operand of the 
IKJNAME macro instruction for the label of this macro instruction. 
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Figure 15-30 shows the format of the IKJSUBF macro instruction. Appendix A 
describes the notation used to define macro instructions. 



label 



IKJSUBF 



Figure 15-30. The IKJSUBF Macro Instruction 



label 



The name you supply as the label of this macro instruction must be the 
same name you have coded as the SUBFLD operand of the IKJNAME 
macro instruction describing the keyword name that takes this subfield. 

The Parameter Control Entry Built by IKJSUBF: The IKJSUBF macro 
instruction generates the parameter control entry (PCE) shown in Figure 15-31. 



Number 
of Bytes 


Field 


Contents or Meaning 


1 

2 


000 

...0 0000 


Flags. These flags indicate which type of PCE this is. 

This PCE indicates an end-of-field. These end-of-field indicators are 
present in IKJSUBF and IKJENDP PCEs; they indicate the end of a 
previous subfield or of the PCL itself. 

Reserved. 

This field contains a hexadecimal number representing the offset within 
the PCL to the first IKJKEYWD PCE or to the next end-of-field 
indicator if there are no keywords in this subfield. 



Figure 15-31. The Parameter Control Entry Built by IKJSUBF 



IKJENDP - Ending the Parameter Control List 



Execute the IKJENDP macro instruction to inform the parse service routine that 
it has reached the end of the parameter control list built for this command. 

Figure 1 5-32 shows the format of the IKJENDP macro instruction. Appendix A 
describes the notation used to define macro instructions. 



IKJENDP 



Figure 15-32. The IKJENDP Macro Instruction 

The Parameter Control Entry Built by IKJENDP: The IKJENDP macro 
instruction generates the parameter control entry (PCE) shown in Figure 15-33. 
It is merely an end-of-field indicator. 



Number 
of Bytes 


Field 


Contents or Meaning 


1 


000 

...0 0000 


Flags. These flags are set to indicate end-of-field. 

End-of-field indicator. Indicates the end of the PCL. 
Reserved. 



Figure 15-33. The Parameter Control Entry Built by IKJENDP 
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IKJRLSA - Releasing Virtual Storage Allocated by Parse 



Execute the IKJRLSA macro instruction to release virtual storage allocated by 
the parse service routine and not previously released by the parse service routine. 
This storage consists of the parameter descriptor list (PDL) returned by the parse 
service routine and any virtual storage obtained for new data received by parse as 
a result of a prompt. 

If the return code from the parse service routine is non-zero, all virtual storage 
allocated by parse has been freed by the parse service routine. In that case, this 
macro instruction need not be issued, but will not cause an error if it is issued. 

Figure 15-34 shows the format of the IKJRLSA macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 



label 


IKJRLSA 


Address of the answer place 
(1-12) 



Figure 15-34. The IKJRLSA Macro Instruction 

address of the answer place 

The address of the word in which the parse service routine placed a pointer 
to the PDL when control was returned to the command processor. This 
address may be loaded into one of the general registers 1 through 12, right 
adjusted with the unused high order bits set to zero. See "Passing Control 
to the Parse Service Routine" for a description of the parse parameter list. 



Passing Control to the Parse Service Routine 



You pass control to the parse service routine by issuing a CALLTSSR macro 
instruction specifying IKJPARS as the entry point. Before you invoke the parse 
service routine however, you must build a parse parameter list (PPL), and place 
its address into register 1 . This PPL must remain intact until the parse service 
routine returns control to the calling routine. Figure 15-35 shows this flow of 
control between a command processor and the parse service routine. 
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Command Processor 



CALLTSSR 



EP = IKJPARS 



Reg. 1 y 



> 



Parse Service Routine 



r PPL 



+ 12J 



+ 16] 



UPT 



ECT 



CP ECB 



PCL 



Answer Place 



Command Buffer 



User Work Area 




Answer Place 



Length 


Offset 


Command Name 


Command Parameters 



Figure 15-35. Control Flow between Command Processor and the Parse Service Routine 



The Parse Parameter List 



The parse parameter list (PPL) is a seven-word parameter list' containing addresses 
required by the parse service routine. 
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The PPL is defined by the IKJPPL DSECT. Figure 15-36 shows the format of 
the parse parameter list. 



Number 
of Bytes 


Field 


Contents or Meaning 


4 
4 
4 

4 

4 

4 
4 


PPLUPT 
PPLECT 
PPLECB 

PPLPCL 

PPLANS 

PPLCBUF 
PPLUWA 


The address of the user profile table. 

The address of the environment control table. 

The address of the command processor's event control block. The ECB 
is one word of storage, declared and initialized to zero by the command 
processor. 

The address of the parameter control list created by the command 
processor using the parse macro instructions. Use the label on the 
IKJPARM macro instruction as the symbolic address of the PCL. 

The address of a fullword of virtual storage, supplied by the calling 
routine, in which the parse service routine places a pointer to the 
parameter descriptor list (PDL). If the parse of the command buffer is 
unsuccessful, parse sets the pointer to the PDL to X'FFOOOOOO'. 

The address of the command buffer. 

The user supplied work area. This field can contain anything that the 
calling routine wishes passed to a validity checking routine. 



Figure 15-36. The Parse Parameter List 



Formats of the PDEs Returned by the Parse Service Routine 



The parse service routine returns the results of the scan of the command buffer to 
the command processor in a parameter descriptor list (PDL). The PDL, built by 
parse, consists of the parameter descriptor entries (PDE), which contain pointers 
to the parameters, indicators of the options specified, and pointers to the subfield 
parameters entered with the command operands. 

Use the IKJPARMD DSECT to map the PDL and each of the PDEs. Base the 
IKJPARMD DSECT on the PDL address returned by the Parse service routine. 
The PPLANS field of the parse parameter list points to a fullword of storage that 
contains the address of the PDL. Then use the labels you used on the parse 
macro instructions to access the corresponding PDEs. 

The format of the PDE depends upon the type of parameter parsed. For a 
discussion of parameter types, see the topic "Command Parameter Syntax." The 
following description of the possible PDEs within a PDL shows each of the PDE 
formats and the type of parameters they describe. 



The PDL Header 



The PDL begins with a two-word header. The DSECT = operand of the 
IKJPARM macro instruction provides a name for the DSECT created to map the 
PDL. Use this name as the symbolic address of the beginning of the PDL header. 



+ 



A pointer to the next block of virtual storage 



+ 4 



Subpool number 



+ 4 



Length 
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Pointer to the next block of virtual storage: 

The parse service routine gets virtual storage for the PDL and for any data 
received as the result of a prompt. Each block of virtual storage obtained 
begins with another PDL header. The blocks of virtual storage are forward 
chained by this field. A forward-chain pointer of X'FFOOOOOO' in this field 
indicates that this is the last storage element obtained. 

Subpool number: 

This field will always indicate subpool 1 . All virtual storage allocated by 
the parse service routine for the PDL and for data received from a prompt 
is allocated from subpool 1 . 

Length: 

This field contains a hexadecimal number indicating the length of this block 
of real storage (this PDL); the length includes the header. 



PDEs Created for Positional Parameters 



The labels you use to name the macro instructions provide access to the 
corresponding PDEs. The positional parameters described by the IKJPOSIT, 
IKJTERM, IKJOPER, IKJRSVWD and the IKJIDENT macro instructions have 
the following PDE formats. 

SPACE, DELIMITER: The parse service routine does not build a PDE for 
either a SPACE or a DELIMITER parameter. 

STRING, PSTRING, and QSTRING: The parse service routine uses the 
IKJPOSIT macro to build a two-word PDE to describe a STRING, PSTRING, 
or a QSTRING parameter; the PDE has the following format: 



+ 




A pointer to the character string 










+ 4 


Length 




+ 6 


Flags 


+ 7 


Reserved 



Pointer to the character string: 

Contains a pointer to the beginning of the character string, or a zero if the 
parameter was omitted. 

Length: 

Contains the length of the string. Any punctuation around the character 
string is not included in this length figure. The length is zero if the string is 
omitted or if the string is null. 



Flags: 



The parameter is not present. 

1 The parameter is present. 

.xxx xxxx Reserved bits. 



Note: If the string is null, the pointer is set, the length is zero, and the flag 
bit is 1 . 
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VALUE: The parse service routine uses the IKJPOSIT macro to build a 
two-word PDE to describe a VALUE parameter; the PDE has the following 
format: 



+ 




A pointer to the character string 










+ 4 


Length 




+ 6 


Flags 


+ 7 


Type-char. 



Pointer to the character string: 

Contains a pointer to the beginning of the character string; that is, the first 
character after the quote. Contains a zero if the VALUE parameter is not 
present. 

Length: 

Contains the length of the character string excluding the quotes. 

Flags: 

The parameter is not present. 

1 The parameter is present. 

.xxx xxxx Reserved bits. 

Type-character: 

Contains the letter that precedes the quoted string. 

DSNAME, DSTHING: The parse service routine uses the IKJPOSIT macro 
instruction to build a six-word PDE to describe a DSNAME or a DSTHING 
parameter. The PDE has the following format: 



+ 


A pointer to the dsname 










+ 4 


Length 1 


+ 6 


Flags 1 


+ 7 


Reserved 


+ 8 


A pointer to the member name 










+ 12 


Length2 


+ 14 


Flags2 


+ 15 


Reserved 


+ 16 


A pointer to the password 










+ 20 


Length3 


+ 22 


Flags3 


+ 23 


Reserved 



Pointer to the dsname: 

Contains a pointer to the first character of the data set name. Contains 
zero if the data set name was omitted. Contains a pointer to the USID if it 
is prefixed. 

Lengthl: 

Contains the length of the data set name. If the data set name is contained 
in quotes, this length figure does not include the quotes. When the USID is 
prefixed, this field will contain the total length of the data set name and the 
USID. 
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Flagsl: 

The data set name is not present. 

1 The data set name is present. 

.0 The data set name is not contained within quotes. 

.1 The data set name is contained within quotes. 

..xx xxxx Reserved bits. 

Pointer to the member name: 

Contains a pointer to the beginning of the member name. Contains zero if 
the member name was omitted. 

Length2: 

Contains the length of the member name. This length figure does not 
include the parentheses around the member name. 

Flags2: 

The member name is not present. 

1 The member name is present. 

.xxx xxxx Reserved bits. 

Pointer to the password: 

Contains a pointer to the beginning of the password. Contains zero if the 
password was omitted. 

Length3: 

Contains the length of the password. 

Flags3: 

The password is not present. 

1 The password is present. 

.xxx xxxx Reserved bits. 

JOBNAME: The parse service routine uses the IKJPOSIT macro to build a four 
word PDE to describe a JOBNAME parameter. The PDE has the following 
format: 



+ 


A pointer to the jobname 










+ 4 


Length 1 


+ 6 


Flagsl 


+ 7 


Reserved 


+ 8 


A pointer to the jobid name 










+ 12 


Length2 


+ 14 


Flags2 


+ 15 


Reserved 



Pointer to the jobname: 

Contains a pointer to the beginning of the jobname. Contains zero if the 
jobname was omitted. 

Length!: 

Contains the length of the jobname. The jobname may not be entered in 
quotes. 
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Flagsl: 



The jobname is not present. 
The jobname is present. 



Pointer to the jobid: 

Contains a pointer to the beginning of the jobid. Contains zero if the jobid 
was omitted. 

Length2: 

Contains the length of the jobid. This length figure does not include the 
parentheses around the jobid. 

Flags2: 

The jobid is not present. 

1 The jobid is present. 

.xxx xxxx Reserved bits. 

ADDRESS: The parse service routine uses the IKJPOSIT macro to build a nine 
word PDE to describe an ADDRESS parameter. The PDE has the following 
format: 



+ 


A pointer to the load name 










+ 4 


Length 1 


+ 6 


Flagsl 


+ 7 


Reserved 


+ 8 


A pointer to the entry name 










+ 12 


Length2 


+ 14 


Flags2 


+ 15 


Reserved 


+ 16 


A pointer to the address string 










+ 20 


Length3 


+ 22 


Flags3 


+ 23 


Reserved 


+ 24 


Flags4 


+ 25 

Sign 


+ 26 


Indirect count 






+ 28 


A pointer to the first expression value PDE 










+ 32 


Reserved for use by user validity check routine 











Pointer to the load name: 

Contains a pointer to the beginning of the load module name. Contains 
zero if no load module name was specified. 

Lengthl: 

Contains the length of the load module name, excluding the period. 

Flagsl: 



The load module name is not present. 

1 The load module name is present. 

.xxx xxxx Reserved bits. 
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Pointer to the entry name: 

Contains a pointer to the name of the CSECT; zero if the CSECT name is 
not specified. 

Length2: 

Contains the length of the entry name, excluding the period. 

Flags2: 

The entry name is not present. 

1 The entry name is present. 

.xxx xxxx Reserved bits. 

Pointer to the address string: 

Contains a pointer to the address string portion of a qualified address. 
Contains a zero if the address string was not specified. 

Length3: 

Contains the length of the address string portion of a qualified address. 
This length count excludes the following characters for the following address 
types: 

1. Relative address - excludes the plus sign. 

2. Register address - excludes letters. 

3. Absolute address - excludes period. 

Flags3: 

The bits set in this one-byte flag field indicate whether the address string is 
present and what type of indirect address is represented. 

The address string is not present. 

1 The address string is present. 

.1 A 31-bit indirect address is represented. 

.0 A 24-bit indirect address is represented. 

..xx xxxx Reserved bits. 

Notes: 

1. Bit 1 of Flags3 has no meaning if the indirect count is zero. This bit can 
be on only when the EXTENDED keyword of IKJ POSIT has been 
specified. 

2. Bit and 1 have the same meaning for MVS 370, but 2 through 16 are 
reserved. 

Offset 23: 

This byte is reserved for use by the user's validity check routine. 
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Flags4: 

The bits set in this one-byte flag field indicate the type of address found by 
the parse service routine. 



Bit Setting 


Hex 


Meaning 


0000 0000 


00 


Absolute address. 


1000 0000 


80 


Symbolic address. 


0100 0000 


40 


Relative address. 


0010 0000 


20 


General register. 


0001 0000 


10 


Double precision floating-point register. 


0000 1000 


08 


Single precision floating-point register. 



0000 0100 04 Non-qualified entry name (optionally preceded by a load name). 

Sign: 

Contains the arithmetic sign character used before the expression value 
defined by the first expression value PDE. If the sign field is zero and the 
pointer to the first expression value PDE is non-zero, then the first 
expression value PDE was created due to a switch in indirection symbols 
(?% or %?). If there are no address expression PDEs, then this field is zero. 

Indirect count: 

Contains a number representing the number of levels of indirect addressing. 

Pointer to the first expression value PDE: 

This is a pointer to the first expression value PDE. Contains X'FF000000' 
if there are no expression value PDEs. 

User word for validity checking routine: 

A word provided for use by the user-written validity checking routine. 

Expression Value: If the parse service routine finds an ADDRESS parameter to 
be in the form of an address expression, parse builds an expression value PDE for 
each expression value in the address expression. 

If the EXTENDED keyword is specified on the IKJPOSIT macro, and parse 
encounters an alternating sequence of indirection symbols, (%? or ?%), parse 
completes the current PDE and generates a new expression value PDE. 

These expression value PDEs are chained together, beginning at the eighth word 
of the address PDE built by the parse service routine to describe the address 
parameter. The last expression value PDE is indicated by X'FFOOOOOO' in its 
fourth word, the forward chaining field. 

The parse service routine uses the IKJPOSIT macro to build a four-word PDE to 
describe an expression value; it has the following format: 



+ 


A pointer to the address string 










+ 4 


Length3 


+ 6 


Flags5 


+ 7 


Reserved 


+ 8 


Flags6 


+ 9 

Sign 


+ 10 


Indirect count 






+ 12 


A pointer to the next expression value PDE 
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Pointer to the address string: 

Contains a pointer to the expression value address string. Contains zero if 
this PDE was created due to a switch in indirection symbols. 

Length3: 

Contains the length of the expression value address string. The N is not 
included in this length value. 

Flags5: 

The parse service routine sets bit to indicate the cause of the creation of 
this expression value PDE. The parse service routine sets bit 1 to indicate 
the type of indirect addressing. Bit 1 has no meaning if the indirection 
count is 0. 

1 This expression value PDE created due to + or - sign. 

This expression value PDE created due to ?% or %?. 

.1 A 31-bit indirect address is represented. 

.0 A 24-bit indirect address is represented. 

..xx xxxx Reserved bits. 

Note: Bit and 1 have the same meaning for MVS 370, but 2 through 16 
are reserved. 

Flags6: 

The parse service routine sets these flags to indicate the type of expression 
value. X'00' indicates that this PDE was not created for an expression 
value. 

Bit Setting Hex Meaning 

0000 0000 00 This PDE was created due to a change in indirection symbols. 
0000 0100 04 This is a decimal expression value. 
0000 0010 02 This is a hexadecimal expression value. 

Sign: 

Contains the arithmetic sign character used before the expression value 
defined by the next expression value PDE. If the sign field is zero and the 
pointer to the next expression value PDE is non-zero, then the next 
expression value PDE was created due to a switch in indirection symbols 
(?% or %?). If there are no more PDEs, then this field is zero. 

Indirect count: 

Contains a number representing the number of levels of indirect addressing 
within this particular address expression. 

Pointer to the next expression value PDE: 

Contains a pointer to the next expression value PDE if one is present; 
contains X'FF000000' if this is the last expression value PDE. 

Each time parse encounters a %? sequence, the current PDE will be completed 
with the 31 -bit indirection bit off and the count of 24-bit indirection symbols 
placed in that PDE. A new expression value PDE will be generated in which the 
31-bit indirection bit will be on and the address string address, the decimal value 
bit, and the hexadecimal value bit will all be zero. The number of consecutive 
31 -bit indirection symbols will be placed in the latter PDE. 
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Each time parse encounters a ?% sequence, a complementary process will take 
place. Specifically, the 31 -bit indirection bit will be on and the count of 31 -bit 
indirection symbols will be placed in the PDE. A new expression value PDE will 
be generated in which the 31 -bit indirection bit will be off and the address string 
address, the decimal value bit, and the hexadecimal value bit will all be zero. The 
number of consecutive 24-bit indirection symbols will be placed in the latter PDE. 

Figure 15-37 illustrates the series of PDEs generated by parse when parse finds an 
address expression containing a mixed sequence of 31 -bit and 24-bit indirection 
symbols. The following series of PDEs are generated for 12R%??% + 16n?, an 
address expression with mixed indirection symbols: 



+o 



A pointer to the load name 



+16 



A pointer to the address string 



+20 



+24 



X'20' 



+25 



+22 
X'80' 



+23 

Reserved 



+26 



+28 



A pointer to 1st exp. value PDE 



+32 



Reserved 



(12R%) 

ADDR type PDE 




C 



+0 



+4 



+8 



+9 



'+' 



+9 



+6 



X'40' 



+7 
Reserved 



+10 



+12 



A pointer to 2nd exp. value PDE 



Expression Value PDE 



+6 



X'80' 



+10 



+12 



A pointer to 3rd exp. value PDE 




+0 



A pointer to the address string 



+4 



+8 



X'04' 



+9 



+6 



X'40' 



+7 
Reserved 



+10 



+12 



X'FF 000000' 



(%) 

Expression Value PDE 



(+16N?) 

Expression Value PDE 



Figure 15-37. Series of PDEs Created for Mixed Sequence of Indirection Symbols 
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USERID: The parse service routine uses the IKJPOSIT macro to build a 
four-word PDE to describe a USERID parameter; it has the following format: 



+ 


A pointer to the userid 










+ 4 


Length 1 


+ 6 


Flags 1 


+ 7 


Reserved 


+ 8 


A pointer to the password 










+ 12 


Length2 


+ 14 


Flags2 


+ 15 


Reserved 



Pointer to the userid: 

Contains a pointer to the beginning of the userid. Contains zero if the 
userid was omitted. 

Lengthl: 

Contains the length of the userid. 

Flagsl: 

The userid is not present. 

1 The userid is present. 

.xxx xxxx Reserved bits. 

Pointer to the password: 

Contains a pointer to the beginning of the password. Contains zero if the 
password is omitted. 

Length2: 

Contains the length of the password, excluding the slash. 



Flagsl: 



The password is not present. 

1... .... The password is present. 

.xxx xxxx Reserved bits. 



UID2PSWD: The parse service routine uses the IKJPOSIT macro to build a 
six-word PDE to describe a UID2PSWD parameter. It has the following format: 



+ 


A pointer to the userid 










+ 4 


Lengthl 


+ 6 


Flagsl 


+ 7 


Reserved 


+ 8 


A pointer to password 1 










+ 12 


Length2 


+ 14 


Flags2 


+ 15 


Reserved 


+ 16 


A pointer to password2 










+ 20 


Length3 


+ 22 


Flags3 


+ 23 


Reserved 
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Pointer to the userid: 

Contains a pointer to the beginning of the userid. It contains zero if the 
userid was omitted. 

Lengthl: 

Contains the length of the userid. 

Flagsl: 

Userid is not present. 

1 Userid is present. 

.xxx xxxx Reserved. 

Pointer to password!: 

Contains a pointer to the beginning of password 1. It contains zero if the 
password 1 is omitted. 

Length2: 

Contains the length of password 1, excluding the slash. 

Flags2: 

Passwordl is not present. 

1 Passwordl is present. 

.xxx xxxx Reserved. 

Pointer to password2: 

Contains a pointer to the beginning of password2. It contains zero if 
password2 is omitted. 

Length3: 

Contains the length of password2, excluding the slash. 

Flags3: 

Password2 is not present. 

1 Password2 is present. 

.xxx xxxx Reserved. 

CONSTANT: The parse service routine uses the IKJTERM macro to build a 
five-word PDE to describe a CONSTANT parameter. The PDE has the 
following format: 



+ 


Lengthl 


+ 1 

Length2 


+ 2 


Reserved 


+ 4 


Reserved Word Number 


+ 6 


Flags 


+ 8 


A pointer to the string of digits 






+ 12 


A pointer to the exponent 






+ 16 


A pointer to the decimal point 
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Lengthl: 

Contains the length of the term entered, depending on the type of parameter 
entered as follows: 



• For a fixed-point numeric literal, the length includes the digits but not 
the sign or decimal point. 

• For a floating-point numeric literal, the length includes the mantissa 
(string of digits preceding the letter E) but not the sign or decimal point. 

• For a non-numeric literal, the length includes the string of characters 
but not the apostrophes. 

Length2: 

For a floating-point numeric literal, length2 contains the length of the string 
of digits following the letter E but not the sign. 

Reserved Word Number: 

The reserved word number contains the number of the IKJNAME macro 
that corresponds to the entered name. 

Note: The possible names of reserved words are given by coding a list of 
IKJNAME macros following an IKJRSVWD macro. One IKJNAME 
macro is needed for each possible name. If the name entered does not 
correspond to one of the names in the IKJNAME macro list then this field 
is set to zero. 



Flags: 




Byte 1: 







The parameter is missing. 


1 


The parameter is present. 


.1 


Constant. 


..1 


Variable. 


...1 .... 


Statement number. 


.... 1... 


Fixed-point numeric literal. 


1.. 


Non-numeric literal. 


1. 


Figurative constant. 


1 


Floating-point numeric literal. 



Byte 2: 

Sign on constant is either plus or omitted. 

1 Sign on constant is minus. 

.0 Sign on exponent of floating-point numeric literal is either plus or omitted. 

.1 Sign on exponent of floating-point numeric literal is minus. 

..1 Decimal point is present. 

...x xxxx Reserved bits. 

Pointer to the string of digits: 

Contains a pointer to the string of digits, not including the sign if entered. 
Contains zero if a constant type of parameter is not entered. 
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Pointer to the exponent: 

Contains a pointer to the string of digits in a floating-point numeric literal 
following the letter E, not including the sign if entered. 

Pointer to the decimal point: 

Contains a pointer to the decimal point in a fixed-point or floating-point 
numeric literal. If a decimal point is not entered, this field is zero. 

STATEMENT NUMBER: The parse service routine uses the IKJTERM macro 
to build a five-word PDE to describe a STATEMENT NUMBER parameter. 
The PDE has the following format: 



+ 


Length 1 


+ 1 

Length2 


+ 2 


Length3 


+ 3 

Reserved 


+ 4 


Reserved 


+ 6 


Flags 




+ 8 


A pointer to the program-id 








+ 12 


A pointer to the line number 








+ 16 


A pointer to the verb number 









Lengthl: 

Contains the length of the program-id specified but does not include the 
following period. Contains zero if the program-id is not present. 

Length2: 

Contains the length of the line number entered but does not include the 
delimiting periods. Contains zero if the line number is not present. 

Length3: 

Contains the length of the verb number entered but does not include the 
preceding period. Contains zero if the verb number is not present. 



Flags: 



Byte 1: 



0... 
l... 
.1.. 
..l. 
...l 



The parameter is missing. 
The parameter is present. 
Constant. 
Variable. 

Statement number, 
xxxx Reserved. 



Byte 2: 

xxxx xxxx Reserved. 

Pointer to the program-id: 

Contains a pointer to the program-id, if entered. Contains zero if not 
present. 
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Pointer to the line number: 

Contains a pointer to the line number, if entered. Contains zero if not 
present. 

Pointer to the verb number: 

Contains a pointer to the verb number, if entered. Contains zero if not 
present. 

VARIABLE: The parse service routine builds a five- word PDE (when using the 
IKJTERM macro) to describe a VARIABLE parameter. The PDE has the 
following format: 



+ 


A pointer to the data-name 










+ 4 


Length 1 


+ 5 

Reserved 


+ 6 


Flags 


+ 7 


Reserved 


+ 8 


A pointer to the PDE for the first qualifier 










+ 12 


A pointer to the program-id name 










+ 16 


Length2 


+ 17 

Number of 
Qualifiers 


+ 18 


Number of 
Subscripts 


+ 19 


Reserved 



Pointer to the data-name: 

Contains a pointer to the data-name. If a program-id qualifier precedes the 
data-name, this pointer points to the first character after the period of the 
program-id qualifier. 

Lengthl: 

Contains the length of the data-name. 



Flags: 



Byte 1: 






The parameter is missing. 


1 


The parameter is present. 


.1 


Constant. 


..1. .... 


Variable. 


...1 .... 


Statement number. 


.... xxxx 


Reserved. 



Pointer to the PDE for the first qualifier: 

Contains a pointer to the PDE describing the first qualifier of the 
data-name, if any. This field contains X'FFOOOOOO' if no qualifiers are 
entered. 

Note: The format of the PDE for a data-name qualifier follows this 
description. 

Pointer to the program-id name: 

Contains a pointer to the program-id name, if entered. This field contains 
zero if the optional program-id name is not present. 
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Length2: 

Contains the length of the program-id name, if entered. Contains zero if the 
optional program-id name is not present. 

Number of Qualifiers: 

Contains the number of qualifiers entered for this data-name. (For 
example, if data-name A of B is entered, this field would contain 1 .) 

Number of Subscripts: 

Contains the number of subscripts entered for this data-name. (For 
example, if data-name A(l,2) is entered, this field would contain 2.) 

The format of a data-name qualifier is: 



+ 




A pointer to the data-name qualifier 










+ 4 


Length 




+ 5 

Reserved 


+ 6 


Flags 


+ 7 


Reserved 


+ 8 




A pointer to the PDE for the next qualifier 











Pointer to the data-name qualifier: 

Contains a pointer to the data-name qualifier. 

Length: 

Contains the length of the data-name qualifier. 

Flags: 

xxxx xxxx Reserved. 

Pointer to the PDE for the next qualifier: 

Contains a pointer to the PDE describing the next qualifier, if any. This 
field contains X'FFOOOOOO' for the last qualifier. 

RESERVED WORD: The parse service routine uses the IKJRSVWD macro to 
build a two-word PDE (using the IKJRSVWD macro instruction) to describe a 
RESERVED WORD parameter. The PDE has the following format: 

Note: This PDE is not used when the IKJRSVWD macro instruction is chained 
from an IKJTERM macro instruction. In this case, the 
reserved-word number is returned in the CONSTANT parameter PDE built by 
the IKJTERM macro instruction. 

Reserved-word number: 

The reserved-word number contains the number of the IKJNAME macro 
instruction that corresponds to the entered name. 

Note: The possible names of reserved-words are given by coding a list of 
IKJNAME macros following an IKJRSVWD macro. One IKJNAME 
macro is needed for each possible name. If the name entered does not 
correspond to one of the names in the IKJNAME macro list, this field is set 
to zero. 
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Flags: 

Bytel: 

The parameter is missing. 

1 The parameter is present. 

.xxx xxxx Reserved. 

EXPRESSION: The parse service routine uses the IKJOPER macro to build a 
two-word PDE to describe an EXPRESSION parameter. The PDE has the 
following format: 



+ 


Reserved 










+ 4 


Reserved 


+ 6 


Flags 


+ 7 


Reserved 



Flags: 



The entire parameter (expression) is missing. 

1 The entire parameter (expression) is present. 

.xxx xxxx Reserved. 



IKJIDENT PDE: The parse service routine uses the IKJIDENT macro 
instruction to build a two-word PDE to describe a non-delimiter-dependent 
positional parameter; it has the following format: 



+ 




A pointer to the positional parameter 










+ 4 


Length 




+ 6 


Flags 


+ 7 


Reserved 



Pointer to the positional parameter: 

Contains a pointer to the beginning of the positional parameter. If INTEG 
was specified on the IKJIDENT macro instruction, this will contain a 
pointer to a fullword binary value. 

Contains zero if the positional parameter is omitted. 

Length: 

Contains the length of the positional parameter. 



Flags: 



The parameter is not present. 

1 The parameter is present. 

.xxx xxxx Reserved bits. 
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Effect of List and Range Options on PDE Formats 



The formats of the IKJPARMD mapping DSECT and of the PDEs built by the 
parse service routine are affected by the options you specify in the parse macro 
instructions, as well as by the type of parameter specified. If you specify the 
LIST or the RANGE options in the parse macro instructions describing positional 
parameters, the IKJPARMD DSECT and the PDEs returned by the parse service 
routine are modified to reflect these options. 

LIST: The LIST option may be used with the following positional parameter 
types: 

• USERID 

• DSNAME 

• DSTHING 

• ADDRESS 

• VALUE 

• CONSTANT 

• VARIABLE 

• STATEMENT NUMBER 

• HEX 

• INTEG 

• CHAR 

• Any non-delimiter-dependent positional parameter 

If you specify the LIST option in the parse macro instructions describing the 
above listed positional parameter types, the parse service routine allocates an 
additional word for the PDE created to describe the positional parameter. This 
word is allocated even though a list may not actually be entered by the terminal 
user. If a list is not entered, this word is set to X'FFOOOOOO'. If a list is entered, 
the additional word will be used to chain the PDEs created for each element 
found in the list. Each additional PDE has a format identical to the one 
described for that parameter type within the IKJPARMD DSECT. Since the 
number of elements in a list is variable, the number of PDEs created by the parse 
service routine is also variable. The chain word of the PDE created for the last 
element of the list is set to X'FFOOOOOO'. 
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Figure 15-38 shows the PDL returned by the parse service routine after three 
positional parameters have been entered. In this case, the first two parameters, a 
USERID and a STRING parameter, had been defined as not accepting lists. The 
third parameter, a VALUE parameter, had the LIST option coded in the 
IKJPOSIT macro instruction that defined the parameter syntax. The VALUE 
parameter was entered as a two-element list. 



PDL - Mapped by 1KJPARMD DSECT 



Chain Word 



\ 



PDL Header 



> USERID PDE 



STRING PDE 



VALUE PDE 

(First element of a two element list) 



FF000000 



VALUE PDE 
) (Last element of a two 
element list) 



Figure 15-38. A PDL Showing PDEs Describing a List 



RANGE: The RANGE option may be used with the following positional 
parameter types: 

• HEX (X' ' only) 

• ADDRESS 

• VALUE 

• CONSTANT 

• VARIABLE 

• STATEMENT NUMBER 

• INTEG 

• Any non-delimiter-dependent positional parameter 

If you specify the RANGE option in the parse macro instructions describing the 
above listed positional parameter types, the parse service routine builds two 
identical, sequential PDEs within the PDL returned to the calling routine. Space 
is allocated for the second PDE even though a range may not actually be supplied 
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by the terminal user. If a range is not supplied, the second PDE is set to zero. 
The flag bit which is normally set for a missing parameter will also be zero in the 
second PDE. 

Figure 15-39 shows the PDL returned by the parse service routine after two 
positional parameters have been entered. In this case, the first parameter is a 
USERID parameter and the second parameter is a VALUE parameter that had 
the RANGE option coded in the IKJPOSIT macro instruction that defined the 
parameter syntax. For this example, the VALUE parameter was not entered as a 
range, and, consequently, the second PDE is set to zero. 



PDL - Mapped by IKJPARMD DSECT 



































0"* ■ - *"0 


0-» *.<) 


0-**O 


0-*W) 



PDL Header 



> USERID PDE 



VALUE PDE 

(May be entered as a Range) 

VALUE PDE built to receive second element of Range. 
(Parameter was not entered as a Range) 



Figure 15-39. A PDL Showing PDEs Describing a Range 



Combining the LIST and RANGE Options: If you specify both the LIST and 
RANGE options in a parse macro instruction describing a positional parameter, 
the parse service routine builds two identical PDEs within the PDL returned to 
the calling routine. Both of these PDEs are formatted according to the type of 
positional parameter described. These two PDEs describe the RANGE. An 
additional word is appended to the second PDE for the purpose of chaining any 
additional PDEs built to describe the LIST. 

Figure 15-40 shows this general format. 
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PDL - Mapped by IKJPARMD DSECT 



Chain Word 



PDL Header 



PDE 



Identical PDE 

(Parameter may be entered as a range) 

(Parameter may be entered as a list) 



, j , 1 \ PDE 

I I I I 

I I 1 

■ | p — — • > Identical PDE 

r- l__l__J J 

I Chain Word *~~K 

\ 
\ 

\ 



Figure 15-40. A PDL Showing PDEs Describing LIST and RANGE Options 



If you have specified both the LIST and the RANGE options in the parse macro 
instruction describing a positional parameter, the user at the terminal has the 
option of supplying a single parameter, a single range, a list of parameters, or a 
list of ranges. The construction of the PDL returned by the parse service routine 
can reflect each of these conditions. 

Figure 15-41 shows the PDL returned by the parse service routine if the user 
enters a single parameter. 



Chapter 15. Command Scan and Parse -- Determining the Validity of Commands 15-79 





PDL - Mapped by IKJPARMD DSECT 


> PDL Header 

} PDE - Filled in 

> Identical PDE - Zeroed 
) Chain Word 


















0* ^0 


0-. M> 


0-» -M> 


0-*- -M) 


FF 000000 







Figure 15-41. PDL - LIST and RANGE Acceptable, Single Parameter Entered 



As Figure 15-41 further shows, the second PDE and the chain word are both set 
to zero by the parse service routine, if the LIST and RANGE options were coded 
in the macro instruction describing the parameter, but the user entered a single 
parameter. 

Figure 1 5-42 shows the PDL returned by the parse service routine if the user 
enters a single range of the form: 

parameter :parameter 





PDL - Mapped by IKJPARMD DSECT 








> PDL Header 
f PDE -Filled in 

} Identical PDE - Filled in 
/ Chain Word 






















FFOOOOOO 









Figure 15-42. PDL - LIST and RANGE Acceptable, Single Range Entered 



As Figure 1 5-42 further shows, both PDEs are filled in to describe the single 
RANGE parameter entered by the user. The chain word is set to X'FF000000' to 
indicate that there are no elements chained onto this one; that is, the parameter 
was not entered in the form of a LIST. 
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Figure 15-43 shows the format of the PDL returned by the parse service routine if 
the user enters a list of parameters in the form: 

(parameter , parameter , . . . ) 



PDL - Mapped by IKJPARMD DSECT 



0-*-*-0 0—- M) 



Chain Word 



PDL Header 



PDE - Filled in 



Identical PDE - Zeroed 




<)-•— M> 0-*-*-0 



Chain Word 



PDE -Filled in 



Identical PDE - Zeroed 




Figure 15-43. PDL - LIST and RANGE Acceptable, LIST Entered 



As Figure 1 5-43 further shows, each of the first PDEs and the chain word 
pointers are filled in by the parse service routine to describe the list of parameters 
entered by the user. The second, identical PDEs are zeroed to indicate that the 
parameter was not entered in the form of a range. 

The last set of PDEs on the chain will contain X'FFOOOOOO' in the chain word to 
indicate that there are no more PDEs on that particular chain. 
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The PDL created by the parse service routine to describe a parameter entered as a 
list of ranges is similar to the one created to describe a list. The difference is that 
the second, identical PDEs are also filled in by the parse service routine to 
describe the ranges entered. 



Figure 15-44 further shows the format of the PDL returned by the parse service 
routine if the user enters a list of ranges in the form: 



(parameter :parameter , parameter : parameter , 



) 



PDL - Mapped by IKJPARMD DSECT 



Chain Word 



PDL Header 



PDE- Filled in 



Identical PDE - Filled in 




Chain Word 



PDE - Filled in 



Identical PDE - Filled in 




Figure 15-44. PDL - LIST and RANGE Acceptable, List of Ranges Entered 
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As Figure 1 5-44 shows, each of the PDEs and each of the second, identical PDEs 
are filled in by the parse service routine to describe the ranges entered. The chain 
words are also filled in to point down through the list of parameters entered. 

The last set of PDEs on the chain will contain X'FFOOOOOO' in the chain word to 
indicate that there are no more PDEs on that particular chain. 



The PDE Created for a Keyword Parameter 



Parse builds a halfword (2-byte) PDE to describe a keyword parameter; it has the 
following format: 



+0 



Number 

+ 2 



Number: 

You describe the possible names for a keyword parameter to the parse 
service routine by coding a list of IKJNAME macro instructions directly 
following the IKJKEYWD macro instruction. One IKJNAME macro 
instruction must be executed for each possible name. 

The parse service routine places into the PDE the number of the IKJNAME 
macro instruction that corresponds to the keyword name entered. 

If the keyword is not entered, and you did not specify a default in the 
IKJKEYWD macro instruction, the parse service routine places a zero into 
the PDE. 



Additional Facilities Provided by Parse 



Translation to Uppercase 



The parse service routine, in addition to determining if command parameters are 
syntactically correct, provides the following services which may be selected by the 
calling routine. 



Positional parameters are ordinarily translated to uppercase unless the calling 
routine specifies ASIS in the IKJPOSIT or IKJIDENT macro instructions. The 
first character of a value parameter, the type-character, is always translated to 
uppercase, however. The string that follows the type character is translated to 
uppercase, unless ASIS is coded in the describing macro instructions. 
Double-byte character set strings in MVS/XA are an exception to this rule. 
Regardless of whether or not you specify ASIS, the contents of the double-byte 
character set string is not translated to upper case. 
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Insertion of Default Values 



Positional parameters (except delimiter and space) and keyword parameters may 
have default values. These default values are indicated to the parse service 
routine through the DEFAULT = operand of the IKJPOSIT, IKJTERM, 
IKJOPER, IKJRSVWD, IKJIDENT, and IKJKEYWD macro instructions. 
When a positional or a keyword parameter is omitted, for which a default value 
has been specified, the parse service routine inserts the default value. 

The parse service routine also inserts the default value you specified if a 
parameter is invalid and the terminal user enters a null line in response to a 
prompt. 



Passing Control to a Validity Checking Routine 



You can provide a validity checking routine to do additional checking on a 
positional parameter. Each positional parameter can have a unique validity 
checking routine. Indicate the presence of a validity checking routine by coding 
the entry point address of the routine as the VALIDCK = operand in the 
IKJPOSIT, IKJTERM, IKJOPER or IKJIDENT macro instructions. 

The parse service routine can call validity checking routines for the following 
types of positional parameters: 



• 


HEX 


• 


VALUE 


• 


ADDRESS 


• 


QSTRING 


• 


USERID 


• 


DSNAME 


• 


DSTHING 


• 


CONSTANT 


• 


VARIABLE 


• 


STATEMENT NUMBER 


• 


EXPRESSION 


• 


JOBNAME 


• 


INTEG 


• 


Any non-delimiter-dependent parameters 



The validity check exit is taken after the parse service routine has determined that 
the parameter is non-null and syntactically correct. If a dsname or userid 
parameter is entered with a password, parse takes the validity check exit after first 
parsing both the userid or dsname and the password. If the terminal user enters a 
list, the validity check routine is called as each element in the list is parsed. If a 
range is entered, the parse service routine calls the validity check routine only 
after both items of the range are parsed. 

Parse invokes all validity checking exit routines in the same addressing mode in 
which parse is invoked. Note that if a SYNCH macro is used to invoke parse, 
the addressing mode of the caller may be different than that in which parse is 
invoked. 

When control is passed from the parse service routine to a validity checking 
routine, the parse service routine uses standard linkage conventions. The validity 
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Insertion of Keywords 



check routine must save parse's registers and restore them before returning control 
to the parse service routine. The parse service routine builds a three-word 
parameter list and places the address of this list into register 1 before branching to 
a validity checking routine. This three-word parameter list has the format shown 
in Figure 15-45. 



Number 
of Bytes 


Field 


Contents or Meaning 


4 
4 
4 


PDEADR 
USERWORD 

VALMSG 


The address of the parameter descriptor entry (PDE) built by parse for 
this syntactically correct parameter. 

The address of the user work area. This is the same address you 
supplied to the parse service routine in the parse parameter list. 

Initialized to X'00000000' by parse. A user-provided validity checking 
routine can place the address of a second level message in this field. 



Figure 15-45. Format of the Validity Check Parameter List 

Your validity checking routines must return a code in general register 1 5 to the 
parse service routine. These codes inform the parse service routine of the results 
of the validity check and determine the action that parse should take. 
Figure 1 5-46 shows the return codes, their meaning, and the action taken by the 
parse service routine. 



Return 
Code 


Meaning 


Action Taken by Parse 



4 
8 
12 


The parameter is valid. 

The parameter is invalid. 

The parameter is invalid. 

The parameter is invalid; 
syntax checking cannot 
continue. 


No additional processing is performed on this parameter 
by the parse service routine. 

The parse service routine writes an error message to the 
terminal and prompts for a valid parameter. 

The validity checking routine has issued an error 
message; parse prompts for a valid parameter. 

The parse service routine stops all further syntax 
checking and returns to the calling routine. 



Figure 15-46. Return Codes from a Validity Checking Routine 

If the parse service routine receives a return code of 4 or 8, the new data entered 
in response to the prompt is parsed as if it were the original data and control is 
again passed to the validity check routine. This cycle continues until a valid 
parameter is obtained. 



Some keyword parameters may imply other keyword parameters. You may 
specify that other keywords are to be inserted into the parameter string when a 
certain keyword is entered. Use the INSERT operand of the IKJNAME macro 
instruction to indicate that a keyword or a list of keywords is to be inserted 
following the named keyword. The inserted keywords are processed as if they 
were entered from the terminal. 
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Issuing Second Level Messages 



Prompting 



You may supply second level messages to be chained to any prompt message 
issued for a positional parameter (keyword parameters are never required). Use 
the HELP operand of the IKJPOSIT, IKJTERM, IKJOPER, IKJRSVWD or 
IKJIDENT macro instructions to supply these second level messages to the parse 
service routine. You can supply up to 255 second level messages for each 
positional parameter. One second level message is issued each time a question 
mark is entered from the terminal. If a question mark is entered and no second 
level messages were provided, or they have all been issued in response to previous 
question marks, the terminal user is notified that no help is available. 

If a user-provided validity checking routine returns the address of a second level 
message to the parse service routine, that second level message or chain will be 
written out in response to question marks entered from the terminal. The original 
second level chain, if one was present, is deleted. 

If the validity check exit supplies a second level message that resides above 16 
megabytes, parse will copy it to storage below 16 megabytes so that PUTLINE 
and TPUT can handle the message. 

The format of these second level messages is the same as the HELP second level 
message portion of the PCE for the macro from which the validity checking 
routine received control. 



The parse service routine prompts the terminal user if the command parameters 
found are incorrect or if required parameters are missing. It allows the terminal 
user to enter a missing parameter or correct an incorrect one without having to 
reenter the entire command. The parse service routine prompts, and the terminal 
user must respond, in the following situations: 

1 . A userid or dsname was entered with a slash but without a password. 

2. A parameter is syntactically invalid. 

3. A keyword is ambiguous, that is, it is not clear to the parse service routine 
which keyword of several similar ones is being entered. 

4. A required positional parameter is missing. The requirement for a particular 
positional parameter and the prompting message to be issued if that 
parameter is not present, are specified to the parse service routine through the 
PROMPT operand of the IKJPOSIT, IKJTERM, IKJOPER, IKJRSVWD, 
and IKJIDENT macro instructions. The parse service routine puts out the 
prompting message supplied in the macro instruction. 

5. A validity check exit indicates that a parameter is invalid. 

There are a number of rules that govern the processing of responses entered from 
the terminal after a prompt. 

1. All of the new data entered is parsed before the scan of the original command 
is resumed. 
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2. Unless otherwise stated in the command syntax definition, the new parameter 
is entered as it is entered in the original command. See "Command 
Parameter Syntax" for exceptions to this rule. 

3. In general, additional parameters may be entered along with the data 
prompted for. It must be kept in mind, however, that all of the new data 
entered is parsed before the scan of the material in the original command 
buffer is resumed. A problem could occur in a situation where a command is 
entered followed by two positional parameters and a keyword, and the first 
positional parameter is invalid. The parse service routine issues a prompt for 
the first positional parameter. When the user at the terminal reenters that 
first positional parameter, it would be invalid to enter additional keywords 
along with it. The additional keywords would be scanned before the second 
positional parameter and an error condition would result when the parse 
service routine returned to the original command buffer and found a 
positional parameter. 

Note that if the parameter prompted for is within a subfield, only parameters 
valid within that subfield may be entered along with the parameter prompted 
for. 

4. In general, a null response is acceptable only for optional parameters. 
However, if a null response is entered for an optional parameter that has a 
default, parse inserts the default. If a prompt for a required parameter is 
answered by a null response from the terminal, parse reissues the prompt 
message. The parse service routine continues prompting until a correct 
parameter is entered. The terminal user can request termination by entering 
an attention. 

Parse will always accept a null response to a prompt for a password, whether 
or not the dsname or userid parameters are required. It is the responsibility 
of the routine using the parse service routine to ensure that the correct 
password was entered if one was required, by checking the password pointed 
to by the PDE returned by the parse service routine. 

5. If a required parameter which may be entered in the form of a list is missing, 
or if it was entered as a single parameter (not as a list), and that single 
parameter is incorrect, parse will not accept a list after the prompt. The user 
at the terminal must enter a single parameter. 

If, however, the item was entered as a list but an item within the list is 
invalid, the parse service routine accepts one or more parameters after the 
prompt. The parse service routine considers these newly entered parameters 
to be part of the original list. Parameters that are not valid in the list may be 
entered from the terminal in response to this prompt. 

If the last item in a list is found to be invalid, parse only accepts one 
parameter after a prompt. 

6. If the parse service routine determines that a parameter is invalid, the invalid 
portion of the parameter is indicated in the error message. The remainder of 
the parameter is not yet parsed. The user must reenter as much of the invalid 
parameter as was indicated in the error message. This situation often occurs 
if a dsname parameter or userid parameter is entered with blanks between the 
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dsname or userid and the password. The dsname or userid may be invalid 
but the password is still good and will be parsed after a new dsname or userid 
is entered in response to the prompt. 

The parse service routine always attempts to obtain syntactically correct 
parameters before returning to the calling routine. However, this is not always 
possible. The terminal user may have requested that no prompt messages be sent 
to the terminal, or the command being parsed may have come from a procedure. 
In these cases, an error message is issued and a code is returned to the calling 
routine indicating that a correct command could not be obtained. Any second 
level messages that would ordinarily be appended to the request for new data are 
appended to the error message. 



Examples of Using the Parse Service Routine 



Example 1 



This example shows how the parse macro instructions could be used within a 
command processor to describe the syntax of an EDIT command to the parse 
service routine. 

The sample EDIT command we are describing to the parse service routine has the 
following format: 



dsname 



PLI 



number ["number] ~j [~ CHAR60 ) 
2 [_ 72 _|J|_CHAR48 



FORT 
ASM 
TEXT 
_DATA 

SCAN "I 

noscan J 

NUM 1 

NONUMj 

BLOCK (number) 
BLKSIZE( number; 

LINE (number) 



Figure 15-47 shows the sequence of parse macro instructions that would describe 
the syntax of this EDIT command to the parse service routine. 
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Figure 15-47. Coding Exai»|»te 1 - Using Parse Mscms to Describe Command Parameter Syntax 

The parse macro instructions shown in Figure 15-47 perform two distinct 
functions when executed: 

1. Build the parameter control list describing the syntax of the EDIT command 
parameters. The PCL is used by the parse service routine during its scan of 
the parameters within the command buffer. 

2. Create the IKJPARMD DSECT (defaulted to on the IKJPARM macro 
instruction) that you use to map the parameter descriptor list returned by the 
parse service routine after it scans the parameters within the command buffer. 

Your code never refers to the PCL; it is used only by the parse service routine. 
Therefore, it is not shown in the example. 
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Figure 15-48 shows the IKJPARMD DSECT created by the expansion of the 
parse macro instructions. 
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Figure 15-48. An IKJPARMD DSECT (Example 1) 



If a terminal user entered the above described EDIT command in the form: 

edit sysfile/x pll(3) nonum block 

the parse service routine would prompt for the blocksize as follows: 

ENTER BLOCKSIZE 

The user at the terminal might respond with: 

160 

The parse service routine would then complete the scan of the command 
parameters, build a parameter descriptor list (PDL), place the address of the PDL 
into the fullword pointed to by the fifth word of the parse parameter list, and 
return to the calling program. 

The calling routine uses the address of the PDL as a base address for the 
IKJPARMD DSECT. 

Figure 15-49 shows the PDL returned by the parse service routine. The symbolic 
addresses within the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply, and the meanings of the fields within 
the PDL are explained to the right of the PDL. 
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IKJPARMD 
DSECT 



PDL 



IKJPARMD 



DSNAM 



TYPE, SCAN 
NUM, BLOCK 
LINE 
PL1COL1 

PL1COL2 

PL1TYPE 
BLKNUM 

LINNUM 



Description of 
Field Contents 









Pointer to SYSFILE 


7 


1 















Pointer to X 


1 


1 




1 


2 


2 


1 





Unused 


Pointer to 3 


1 


1 




Pointer to 72 


2 


1 




1 


Unused 


Pointer to 160 


3 


1 
















PDL Header. Used only by 
IKJRLSA 



Data Set Name 

No member name 

Password 

PL1, NOSCAN 
NONUM, BLOCK 
LINE not specified 
3 was specified 

72 is the default 

CHAR60 is the default 
160 was prompted for 

LINNUM not specified 



Figure 15-49. The IKJPARMD DSECT and the PDL (Example 1) 



Example 2 



This example shows how the parse macro instructions could be used to describe 
the syntax of a sample AT command that has the following syntax: 



COMMAND 


OPERANDS 


AT 




stmt 1 

( stint- l,stmt-2, . . . )| (cmd, chain) COUNT (integer) 

stmt- 3 : stmt-4 ) 
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Figure 15-50 shows the sequence of parse macro instructions that describe this 
sample AT command to the parse service routine. 
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Figure 15-50. Coding Example 2 - Using Parse Macros to Describe Parameter Syntax 

The parse macro instructions shown in Figure 15-50 perform two distinct 
functions when executed: 



1. Build the parameter control list describing the syntax of the command 
parameters. This PCL is then used by the parse service routine during its 
scan of the parameters in the command buffer. 

2. Create the IKJPARMD DSECT that you use to map the parameter 
descriptor list. The PDL is returned by the parse service routine after it scans 
the parameters in the command buffer. 

Note: Your code never refers to the PCL; it is used only by the parse service 
routine. Therefore, the parameter control list is not shown in the example. 

Figure 15-51 shows the IKJPARMD DSECT created by the expansion of the 
parse macro instructions. 
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Figure 15-51. An IKJPARMD DSECT (Example 2) 



In this example, if the terminal user entered the above described command 
incorrectly like this: 

at 200/3 (list all) count (a) 

the parse service routine would prompt the terminal user with the message: 

INVALID STATEMENT NUMBER, 200/3 
REENTER 
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The user might respond with: 
200.3 

the parse service routine would then prompt the user with: 

INVALID COUNT, a 
REENTER 

The user might respond with: 
3 

This sequence resulted in the syntactically correct command of: 

at 200.3 (list all) count (3) 

The parse service routine would then build a parameter descriptor list (PDL) and 
place the address of the PDL into the fullword pointed to by the fifth word of the 
parse parameter list. 

The parse service routine then returns to the caller and the caller uses the address 
of the PDL as a base address for the IKJPARMD DSECT. 

Figure 15-52 shows the PDL returned by the parse routine. The symbolic 
addresses of the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply. A description of the fields within the 
PDL is shown on the right. 



Chapter 15. Command Scan and Parse ~ Determining the Validity of Commands 15-93 





IKJPARMD 
DSECT 
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Description of 
Field Contents 














PARS EAT 


STMTPCE 
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POSITPCE 

KEYPCE 
IDENTPCE 




I PDL Header, used only by 
[ IKJRLSA 

Lengths (program -id, line no. 
and verb no. ) 

Parameter is present 
No program - id 
Line number 
Verb number 










PDE Offset 
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X'90' 
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Pointer to 200 


Pointer to 3 
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Double PDE for RANGE option, 
but not entered 
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X'OO' 
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X'FFOOOOOO* 


LIST option not entered 

First character after ) 

Length , parameter is present 

First keyword 

Subfield 

Length, parameter is present 


Pointer to LIST in string 
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Pointer to 3 
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Figure 15-52. The IKJPARMD DSECT and the PDL (Example 2) 



Example 3 



This example shows how the parse macro instructions could be used to describe 
the syntax of a sample LIST command that has the following syntax: 



COMMAND 



OPERANDS 



LIST 



symbol PRINT (symbol) 



1 5-94 TSO/E Guide to Writing a TMP or a CP 



Figure 1 5-53 shows the sequence of parse macro instructions that describe this 
sample LIST command to the parse service routine. 
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Figure 15-53. Coding Example 3 - Using Parse Macros to Describe Parameter Syntax 

The parse macro instructions shown in Figure 15-53 perform two distinct 
functions when executed: 

1. Build the parameter control list describing the syntax of the command 
parameters. This PCL is then used by the parse service routine during its 
scan of the parameters in the command buffer. 

2. Create the IKJPARMD DSECT that you use to map the parameter 
descriptor list. The PDL is returned by the parse service routine after it scans 
the parameters in the command buffer. 

Note: Your code never references the PCL; it is used only by the parse service 
routine. Therefore, the parameter control list for the example is not shown. 

Figure 15-54 shows the IKJPARMD DSECT created by the expansion of the 
parse macro instructions. 
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Figure 15-54. An IKJPARMD DSECT (Example 3) 



In this example, if the terminal user entered the above described command 
incorrectly like this: 

list a of 1 in 3(1) print (d) 

the parse service routine would prompt the terminal user with: 

INVALID SYMBOL, a...l in 3(1) 
REENTER 
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The user might respond with: 

a of b in 3(1) 

the parse service routine would then prompt with: 

INVALID SYMBOL, a... 3(1) 
REENTER 

The user might respond with: 

a of b in c(l) 

This sequence resulted in the syntactically correct command of: 

list a of b in c(l) print(d) 

The parse service routine would then build a parameter descriptor list (PDL) and 
place the address of the PDL into the fullword pointed to by the fifth word of the 
parse parameter list. 

The parse service routine then returns to the caller and the caller uses the address 
of the PDL as a base address for the IKJPARMD DSECT. 

Figure 1 5-55 shows the PDL returned by the parse service routine. The symbolic 
addresses of the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply. A description of the fields within the 
PDL is shown on the right. 
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Figure 15-55. The IKJPARMD DSECT and the PDL (Example 3) 
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Example 4 



This example shows how the parse macro instructions could be used to describe 
the syntax of a sample WHEN command that has the following syntax: 



COMMAND 



OPERANDS 



WHEN 



faddr 
lexpress 



ion/ 



(subcommand chain) 



Figure 15-56 shows the sequence of parse macro instructions that describe this 
sample WHEN command to the parse service routine. 
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Figure 15-56. Coding Example 4 - Using Parse Macros to Describe Parameter Syntax 

The parse macro instructions shown in Figure 15-56 perform two distinct 
functions when executed: 

1 . Build the parameter control list describing the syntax of the command 
parameters. This PCL is then used by the parse service routine during its 
scan of the parameters in the command buffer. 

2. Create the IKJPARMD DSECT that you use to map the parameter 
descriptor list. The PDL is returned by the parse service routine after it scans 
the parameters in the command buffer. 

Note: Your code never references the PCL; it is used only by the parse service 
routine. Therefore, the parameter control list for this example is not shown. 

Figure 15-57 shows the IKJPARMD DSECT created by the expansion of the 
parse macro instructions. 
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Figure 15-57. An IKJPARMD DSECT (Example 4) 



In this example, if the terminal user entered the above described command 
incorrectly like this: 

when (a) (list b) 

the parse service routine would prompt the terminal user with: 

ENTER OPERATOR 

The user might then respond: 

eq 

the parse service routine would then prompt with: 

INVALID EXPRESSION, (a eq) 
REENTER 

The user might respond then with: 

(a eq b) 

This sequence resulted in a syntactically correct command of: 

when (a eq b) (list b) 

The parse service routine would then build a parameter descriptor list (PDL) and 
place the address of the PDL into the fullword pointed to by the fifth word of the 
parse parameter list. 

The parse service routine then returns to the caller and the caller uses the address 
of the PDL as a base address for the IKJPARMD DSECT. 

Figure 15-58 shows the PDL returned by the parse service routine. The symbolic 
addresses of the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply. A description of the fields within the 
PDL is shown on the right. 
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Figure 15-58. The IKJPARMD DSECT and PDL (Example 4) 
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Return Codes from the Parse Service Routine 



When it returns to the program that invoked it, the parse service routine provides 
one of the following return codes in general register 15: 

Code Meaning 

decimal 

Parse completed successfully. 

4 The command parameters were incomplete and parse was unable to prompt. 

8 Parse did not complete. An attention interruption occurred during parse processing. 

12 The parse parameter block contains invalid information. 

16 Parse issued a GETMAIN and no space was available. 

20 A validity checking routine requested termination. 

24 Conflicting parameters were found on the IKJTERM, IKJOPER, or IKJRSVWD macro 

instruction. 

28 The terminal has been disconnected. 

No error message is needed for return codes 4 and 20. The parse service routine 
issues a message before returning a code of 4 and the validity checking routine 
issues an error message before it requests termination. The GNRLFAIL routine 
can be invoked to issue meaningful error messages for the other parse return 
codes. See "GNRLFAIL/VSAMFAIL Routine (IKJEFF19)" in this book. 
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Chapter 16. Catalog Information Routine (IKJEHCIR) 



The catalog information routine retrieves information from the system catalog. 
This information may include data set name, index name, control volume address, 
or volume ID. The information may be requested from a specific user catalog, or, 
if no catalog was specified, the system default catalog search is used. An entry 
code indicates the requested kind of information as follows: 

• The next level qualifiers for a name 

• All names having the same name as the high-level qualifier and the data set 
type associated with each name 

• The volume serial numbers and device types associated with a name 

The requester can also ask for combinations of the information above. 

The catalog information routine resides in SYS1.LPALIB and executes with the 
protection key of the caller. 

IKJEHCIR may be invoked in either 24- or 31 -bit addressing mode. However, all 
input passed to IKJEHCIR must reside below 16 megabytes. IKJEHCIR 
executes in 24-bit addressing mode and returns control in the same addressing 
mode in which it is invoked. 

The catalog information routine parameter list (CIRPARM) is shown in 
Figure 16-1. 



Number 
of Bytes 


Field 


Contents or Meaning 


1 


CIROPT 


Entry code/options used. See Figure 16-2. 


2 




Reserved. 


1 


CIRLOCRC 


Locate return code. 


4 


CIPSRCH 


Address of the search argument. This search argument is a userid and 
a data set name which are names of catalog index levels. 


4 


CIRCVOL 


Address of the volume ID of CVOL. If not given, SYSRES is 
assumed. 


4 


CIRWA 


Address of the user work area. See Figure 16-3 for the user work area. 


4 


CIRSAVE 


Address of a 72-byte save area. 


4 


CIRPSWD 


Address of an 8-byte password or zero. 



Figure 16-1. Catalog Information Routine Parameter List (CIRPARM) 
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The CIROPT values and data returned are shown in Figure 16-2. 



Code 


Meaning 


Data Required 


x'or 


Move the data set names having one 
more level of qualifier above what the 
user specified. 


8-byte qualifiers are moved into the 
user's work area. 


X'02' 


Move all data set names to the user 
work area. 


44-byte data set names are moved to 
the user work area. 


X'04' 


Get a volume associated with a given 
data set name. 


Volume information is moved to the 
user work area. See Figure 16-4 for 
volume information format. 


X'05' 


Get the next level data set name and 
volume information. 


44-byte data set name and volume 
information is moved to the user work 
area. 


X'06' 


Get all level data set names and 
volume information. 


44-byte data set name followed by 
volume information is moved to the 
user work area for all levels. 



Figure 16-2. Data Returned from Valid CIROPT Values 

The user work area that is based on CIRWA is shown in Figure 16-3. 



Number 
of Bytes 


Field 


Contents or Meaning 


2 

2 

Variable 


AREALN 

DATALIN 

DATA 


Length of work area. 
Length of data returned + 4. 
The area data is stored. 



Figure 16-3. User Work Area for CIRPARM 

Figure 16-4 describes the format of the volume information. 



Number 
of Bytes 


Field 


Contents or Meaning 


1 




Reserved. 


1 




Number of volume entries. 


4 


DEVTYP 


Device type. 


6 


VOLSER 


Volume serial number. 


2 


FILESEQ 


File sequence number. (This field is provided for compatibility with the 
OS/VS catalog, and is used for non-VSAM data sets that reside on tape 
volumes.) 


1 




Reserved. (Contains X'FF'.) 



Figure 16-4. Volume Information Format 
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Return Codes from IKJEHCIR 



The IKJEHCIR return codes have the following meaning: 
Return Code Meaning 

Hexadecimal 

00 Successful completion of the request. 

04 The LOCATE macro instruction has failed. The LOCATE return code will be stored 

in CIRLOCRC. 

0C Volumes were returned by LOCATE, indicating a dsname (fully qualified) was passed 

in the parameter list but options other than volumes were requested. The list of the 
volumes returned by LOCATE is in the work area. 



Return Codes from LOCATE 



The LOCATE return codes have the following meaning: 

Return Code Meaning 

Hexadecimal 

00 Successful completion of the request. 

04 Required VSAM volume was not mounted or the specified volume was not open. 

08 The data set name qualifier was not found. 

18 A permanent I/O error was found when processing the catalog. 

20 User work area outside user region or invalid user-supplied parameter list. 

24 User catalog must be allocated and opened. 

2C Work area too small. 

38 Password verification failure. 

3C STEPCAT or JOBCAT not open. 
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Chapter 17. Default Service Routine (IKJEHDEF) 



The default service routine (IKJEHDEF) constructs a fully-qualified data set 
name when the calling routine provides a partially-qualified data set name. A 
fully-qualified data set name has three fields: a userid, a data set name, and a 
descriptive qualifier. 

Use the CALL, CALLTSSR or LINK macro instruction to invoke the default 
service routine. 

IKJEHDEF may be invoked in either 24- or 31-bit addressing mode. However, 
all input passed to IKJEHDEF must reside below 16 megabytes. IKJEHDEF 
executes in 24-bit addressing mode and returns control in the same addressing 
mode in which it is invoked. 

At entry, general register 1 must point to the default parameter list (DFPL). 
IKJEHDEF then invokes the catalog information routine (IKJEHCIR) to search 
the system catalog for the required qualifiers. When the search argument is 
satisfied, the default service routine returns to the calling control program. All of 
the general registers are restored except for register 15 which contains the return 
code. 

Note: For additional information concerning the default service routine, see 
Terminal Monitor Program and Service Routines Logic. 
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Chapter 18. Testing a Newly-Written TMP or CP - The TEST 
Command 



The TEST command permits a user at a terminal to test an assembly language 
program, including a user written TMP, command processor, or application 
program. 

You test a program by issuing the TEST command and the various TEST 
subcommands that perform the following basic functions: 

• Execute the program under test from its starting address or from any address 
within the program. 

• Display selected areas of the program as it currently appears in virtual 
storage, or display the contents of any of the registers. 

• Interrupt the program under test at a specified location or locations. Once 
you have interrupted the program, you can display areas of the program or 
any of the registers, or you can issue other subcommands of TEST to be 
executed before returning control to the program being tested. 

• Change the contents of specified program locations in virtual storage or the 
contents of specific registers. You do this with the TEST assignment 
function. 

In addition to these basic debugging functions, the TEST command processor 
provides other functions such as listing data extent blocks (DEBs), data control 
blocks (DCBs), task control blocks (TCBs), program status words (PS Ws), and 
providing a virtual storage map of the program being tested. 

A complete list of the TEST subcommands and a short description of their 
functions is provided in Figure .18-1. 
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Subcommand Name 

ALLOCATE (XA only) 

AND (XA only) 

= (Assignment) 

AT 

ATTRIB (XA only) 

CALL 

CANCEL (XA only) 

COPY 

DELETE 

DROP 

END 

EQUATE 

EXEC (XA only) 

FREEMAIN 

GETMAIN 

GO 
HELP 

LINK (XA only) 
LIST 

LISTALC (XA only) 
LISTBC (XA only) 
LISTCAT (XA only) 

LISTDCB 

LISTDEB 

LISTDS (XA only) 

LISTMAP 

LISTPSW 

LISTTCB 



Function 

Allocates data sets required by a program intended for execution. 

Performs the logical AND function on addresses. 

Assigns values to one or more locations. 

Establishes breakpoints at specified locations. 

Builds a list of attributes for non-VSAM data sets, which are to be 
dynamically allocated. 

Initiates execution of a program at a specified address. 

Halts processing of batch jobs submitted for the terminal. 

Moves data fields or addresses. 

Deletes a load module anywhere in virtual storage. 

Removes symbolic addresses from the symbol table. 

Terminates all functions of the TEST command. 

Adds a symbolic address to the symbol table. 

Executes a CLIST. 

Frees a specified number of bytes of virtual storage. 

Acquires a specified number of bytes of virtual storage for use by the 
program being processed. 

Restarts a program at the point of interruption or at a specified address. 

Lists the TEST subcommands and explains their functions, syntax, and 
operands. 

Invokes the linkage editor service program. 

Displays the contents of specified areas of virtual storage or the contents of 
specified registers. 

Displays a list of data set names allocated during the current TSO session. 

Displays a listing of the contents of the SYS1.BRODCAST data set. 

Lists catalog entries by name or entry type and lists selected fields for each 
entry. 

Lists the contents of a data control block (DCB). You must specify the 
address of the DCB. 

Lists the contents of a data extent block (DEB). You must specify the 
address of the DEB. 

Displays attributes of specific data sets at the terminal. 

Displays a storage map of any virtual storage assigned to a program. 

Displays the program status word (PSW). You can specify the address of 
any PSW. 

Lists the contents of the task control block (TCB). You can specify the 
address of any TCB. 



Figure 18-1 (Part 1 of 2). The TEST Subcommands 
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Subcommand Name Function 

LOAD Loads a program into virtual storage for execution. 

OFF Removes breakpoints. 

OR (XA only) Performs the logical OR function on addresses. 

PROFILE (XA only) Establishes, changes, or lists the user profile. 

PROTECT (XA only) Prevents unauthorized access to a non-VSAM data set. 

QUALIFY Establishes the starting or base location for symbolic or relative addresses; 

resolves external symbols within load modules. 

RENAME (XA only) Changes the name of a non-VSAM cataloged data set or a member of a 

PDS or creates an alias for a member of a PDS. 

RUN Voids all breakpoints so that a program can execute to termination. 

SEND (XA only) Sends a message to another terminal user or to the system operator. 

STATUS (XA only) Displays the status of batch jobs for processing. 

SUBMIT (XA only) Submits one or more batch jobs for processing. 

TERMINAL (XA only) Defines the operating characteristics of your terminal. 

UNALLOC (XA only) Frees data sets under TSO TEST. Because FREE is an alias for the 

FREEMAIN subcommand, you must UNALLOC to free files under TEST. 

WHERE Displays the absolute address of a symbol or entry point, and its relative 

location within the CSECT. 

Figure 18-1 (Part 2 of 2). The TEST Subcommands 



When You Would Use TEST 



There are two basic situations in which you might want to use the TEST 
command: 

1 . You want to test a program currently active in the system. 

2. You want to test a program not currently being executed. 



Testing a Currently Executing Program 



You may want to TEST a currently executing program either because it has 
begun to abnormally terminate, or because you want to check through the current 
environment to see that the program is executing properly. 

• If a program has begun to abnormally terminate, you receive a diagnostic 
message from the terminal monitor program (TMP) and then a READY 
message. The TMP is in effect asking, "Do you want to terminate your 
program or test it?" If you respond with anything but TEST, your program 
is abnormally terminated by the ABEND routine. If, however, you issue the 
TEST command (no program name should be supplied), the TEST command 
processor is given control, and you can use the TEST subcommands to debug 
the defective program. 

• If you just want to look at the current environment of an executing program 
that is not terminating abnormally, enter an attention. The currently active 
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program is not detached and the TMP responds to your interruption by 
issuing its usual READY message. Issue the TEST command (no program 
name) and the currently active program remains in storage under the control 
of the TEST command processor. You can then use the TEST subcommands 
to investigate the current storage situation. 

Note that in the case of both the ABEND or the attention interruption, you 
do not enter a program name following the TEST command. If you enter the 
TEST command followed by the name of the currently active program, you 
lose the current in-storage copy of the program and TEST loads a new copy. 



Testing a Program Not Currently Executing 



The second use of the TEST command processor, testing a program not currently 
being executed, requires that you enter a program name along with the TEST 
command. When the terminal monitor program issues a READY message to 
request a command, enter the command: 

TEST program name 

(There are other optional operands of the TEST command but they are not 
necessary for this example.) The TEST command processor is given control and 
it loads a copy of the named program. The program can be a newly written 
TMP, CP, or application program. 

Programs to be tested in this manner must be link edited members of partitioned 

data sets, or object modules in sequential or partitioned data sets, loadable by the 

Loader. \ 

While the program is under the control of TEST, you can step through the 
program using breakpoints, investigate or alter the environment at any time, 
change instructions or register contents, force entry into various subroutines, and 
perform other debugging operations online and immediately. 

It is this second use of the TEST command processor, especially the debugging of 
newly written code, that this section discusses. For an additional discussion of the 
TEST command and its operands, see TSO/E Command Language Reference. 



Addressing Restrictions 



The TEST command processor can resolve internal and external symbolic 
addresses only if these addresses are available and can be obtained by TEST. 
Within certain limitations, symbolic addresses are available for both object 
modules (processed by the Loader) and load modules (fetched by contents 
supervision). To ensure availability of symbols, use the EQUATE subcommand 
of TEST to define the symbols you intend to use. 

External symbols, such as CSECT names, can be available for both object 
modules and load modules. Object modules require that the Loader had enough 
storage to build in-storage composite external symbol dictionary (CESD) entries. 
Load modules must have been fetched into virtual storage by the tested program 
or by the LOAD subcommand of TEST. 
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Internal symbols are available only for load modules. You can refer to most 
internal symbols in load modules if you specified the TEST parameter during 
both assembly and linkage editing. Certain internal symbols, however, are not 
available. These include the names on EQU, DSECT, LTORG, and ORG 
assembler statements, and the symbolic names contained in system routines that 
operate in zero protection key. 

Provided a module invoked by the tested program is not fetched from the link 
pack area, CSECT names within the module can be accessed. If this module is 
also assembled and link-edited with the TEST parameter, symbolic addresses can 
also be accessed. 

If the necessary conditions for symbol processing are not met, you can use 
absolute, relative, or register addressing, but you cannot refer to symbols, unless 
you have previously defined them with the EQUATE subcommand of TEST. 



Executing a Program under the Control of TEST 



Any program, if it is a link-edited member of a partitioned data set or an object 
module in a sequential or partitioned data set, can be executed under the control 
of the TEST command processor. 

Issue the TEST command followed by the program name and those operands of 
the TEST command that either define the program or are necessary to its 
operation. These operands may consist of: parameters necessary to the operation 
of the program under TEST, the keyword LOAD or OBJECT depending on 
whether the program is a load or an object module, and the keyword CP or 
NOCP, depending upon whether the program to be tested is a command 
processor or not. 

Any parameters that you specify in the TEST command are passed to the named 
program as a standard operating system parameter list; that is, when the program 
under TEST receives control, register one contains a pointer to a list of addresses 
that point to the parameters. 

If the program to be tested is a command processor, include the keyword CP (the 
default is NOCP). The test routine creates a command processor parameter list 
(CPPL), and places its address into register 1 before loading the program. 

Figure 18-2 shows the sequence of operations leading up to and following the 
issuance of the TEST command. 
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Figure 18-2. Issuing the TEST Command 

In Figure 18-2, the following sequence of operations takes place: 

1 . The terminal monitor program issues a READY message to the terminal to 
indicate that the user should enter a command. 

2. The user at the terminal answers with the command: 

TEST (MYPROG) CP 

3. The TMP uses the command scan service routine to determine that a valid 
command has been entered, and invokes TEST via a SYNCH macro. 

4. The TEST command processor, using the parse service routine, determines 
that the user wants a command processor parameter list built and passed to 
the load module (LOAD is the default) MYPROG. TEST builds the CPPL, 
in storage below 16 megabytes, places its address into register one, and 
attaches the TEST loader which transfers control to MYPROG using the 
XCTL macro. XCTL loads and passes control to the tested program based 
on the program's AMODE and RMODE attributes. 

5. The TEST command processor informs the User at the terminal that it is 
ready to accept subcommands. TEST does this by writing the message TEST 
at the terminal. 
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From this point on, the user can use any of the facilities provided by the TEST 
subcommands to test his program. 



Establishing and Removing Breakpoints within a Program 



Use the AT subcommand to establish breakpoints within the program being 
tested. Then issue the GO subcommand to begin execution of the program. To 
begin executing a newly loaded program, enter the subcommand GO - no address 
is required. When the breakpoints are encountered as the program is being 
executed, processing is temporarily halted, and the message A T address is written 
to the terminal. You can then examine the executing program, its registers, and 
data areas to see that it has been executing properly. 

There are two methods of accomplishing this: 

1 . You can specify a list of subcommands on the AT subcommand when you 
establish a breakpoint. When a breakpoint is encountered, the TEST 
command processor issues each of the specified subcommands as if it had 
been entered from the terminal at that time. The subcommands execute and 
display the results of their execution at the terminal. If you specify GO as the 
last subcommand, control is automatically returned to the program under 
TEST at the point of interruption. If you do not specify GO as the last 
subcommand in the list, control is returned to you at the terminal after the 
last subcommand is executed. If you determine from the information 
displayed by the subcommands that your program has executed properly up 
to that breakpoint, issue the GO subcommand. Your program resumes 
execution at the point of interruption and continues execution until another 
breakpoint, or the end of the program, is reached. 

2. If you do not specify a list of subcommands when you issue the AT 
subcommand, the TEST command processor returns control to you at the 
terminal each time a breakpoint is encountered. You can then check on your 
program's execution by entering the TEST subcommands directly from the 
terminal. 

Issue the OFF subcommand with no address operand to remove all breakpoints 
previously established. Issue the OFF subcommand followed by an address, a list 
of addresses, or a range of addresses to remove a single breakpoint, several 
breakpoints, or all breakpoints occurring within the range of addresses. 



Displaying Selected Areas of Storage 



Use the various LIST subcommands to display the contents of a specified area of 
storage, registers, or various control blocks at your terminal, or to write this 
information to a data set. There are six variations of the LIST subcommand that 
display selected areas of storage: 

1. LIST 

2. LISTMAP 

3. LISTTCB 

4. LISTDEB 

5. LISTDCB 

6. LISTPSW 
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LIST: Use the LIST subcommand to display areas of storage or the contents of 
registers. The address required as an operand of the LIST subcommand can be 
one address, a list of addresses, or a range of addresses. The address may be 
specified as a symbolic address if a symbol table exists and contains the requested 
symbolic address. If no symbol table exists (the program was not link-edited or 
did not save a symbol table), you can use the EQUATE subcommand to create a 
symbolic address for any location within the program, or you can specify the 
address as a relative address, an absolute address, or as a register containing an 
address. 

If you use the LIST subcommand to list information found at an address specified 
by a symbol contained in a symbol table, the information is displayed in the 
character type and the length specified in the symbol table. You can, however, 
override the attributes contained in the symbol table by including attribute 
operands on the LIST subcommand. 

Use the LIST subcommand at any point during the execution of your program 
(use AT or an attention interruption to stop the execution of the program) to 
determine whether data areas and registers contain proper data. If the data 
displayed is not what it should be, use the TEST subcommands to determine why 
the data is not as expected, or to modify the data in virtual storage and continue 
execution of the program. 

LISTMAP: Use the LISTMAP subcommand to display at your terminal a map 
of all virtual storage assigned to the program being tested. Some of the 
information displayed after issuance of the LISTMAP subcommand is: 

• Region size 

• Task Control Block address 

• Program name, length, and location in virtual storage 

• Active request blocks, RB types, and the names of the programs associated 
with each of the RBs 

LISTTCB: Use the LISTTCB subcommand to display the entire task control 
block of the program being tested, or any fields of that TCB. The information 
displayed is formatted, and each field is identified according to the field names 
contained in Data Areas. 

If you want to display the TCB for the program being tested, enter the LISTTCB 
subcommand with no address. If you want to display another TCB on the TCB 
queue, you must include the address of the TCB as an operand of the LISTTCB 
subcommand. 

LISTDEB: Use the LISTDEB subcommand to display the basic section and any 
direct access sections of any valid data extent block (DEB), or any fields of that 
DEB. The information displayed is formatted according to the field names of 
the data extent block as contained in Data Areas. 

The LISTDEB subcommand requires the address of a DEB as an operand. 
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LISTDCB: Use the LISTDCB subcommand to display the contents of a data 
control block (DCB). The information displayed is formatted, and each field is 
identified according to the field names contained in the publication Data Areas. 

The LISTDCB subcommand requires the address of a DCB as an operand. If 
you have created the DCB within the program being tested, use the address of the 
DCB macro instruction used to create the DCB. You can also obtain the address 
of the DCB from the DEBDCBAD field of the DEB displayed with the 
LISTDEB subcommand. 

LISTPSW: Use the LISTPS W subcommand to display the current program 
status word or any of the PSWs at your terminal. The PS W is displayed, 
formatted by field. If you issue the LISTPSW subcommand with no address 
following the subcommand, the current PSW is displayed at your terminal. If 
you want to display any of the other PSWs at your terminal, supply the address 
of the PSW you want to see as an operand of the LISTPSW subcommand. A list 
of the permanent virtual storage locations of all PSWs can be found in Principles 
of Operation. 



Changing Instructions, Data Areas, or Register Contents 



Once you have listed those areas of virtual storage that help you determine just 
what has occurred in your program, you can use the assignment function of the 
TEST command to make corrections within the virtual storage copy of the code, 
or to change the contents of data areas or registers. 

Enter the address at which you want the new data entered, a code indicating the 
data type, and the new data you want entered at that address. The address must 
conform to the address restrictions already discussed. The new data must be 
contained within single quotes. The data type codes can be found in TSO/E 
Command Language Reference. 

One problem that can arise during a debugging session occurs when you want to 
replace a section of the program under TEST but the replacement code is longer 
than the section to be replaced. If you type in the beginning address of the 
section to be replaced, followed by a portion of code longer than the segment to 
be replaced, you will overlay some functional code. You can solve this problem 
with the GETMAIN subcommand of TEST. 

Issue the GETMAIN subcommand of TEST to obtain a work area in which to 
build your replacement segment of code. The GETMAIN subcommand displays 
the address of the beginning of the virtual storage area it obtained for you. The 
LOC operand enables you to specify where you want the storage to be obtained 
in terms of below or above 16 megabytes. Use the assignment subcommand of 
the TEST command to place a branch to the new area at the beginning address of 
the code you want to replace in your module. Use the assignment or COPY 
subcommand to build your code segment in the newly obtained area. As the last 
instruction in your newly written code, place a branch back to the point within 
your module at which you want processing to resume. You can then use the GO 
subcommand to restart your program at some point before the branch. Your 
program will execute through the branch instruction and into the newly written 
code. If the new code works, you will execute the new instructions and branch 
back into your original code. Later, you can use the LIST subcommand to 
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display the newly written code in a form useful to you, enter it into your program, 
and reassemble your now executable module. 



Forcing Execution of Program Subroutines 



Certain paths through some programs are difficult to test because the 
combination of events leading to that path is difficult to produce. 

One example of this problem is processing after return codes. Your module might 
respond differently according to the codes returned to it by some other module or 
some other, not yet written, section of code. You can use the AT subcommand to 
insert a breakpoint in your program at the point where it passes control to the 
unavailable code; the assignment function of TEST to set register 15 to the 
desired return code; and the GO subcommand to begin execution of your 
program at the point where control would have been returned. Using this 
sequence of TEST subcommands, you can test your module's response to each 
possible return code. 



Using TEST after a Program ABEND 



If a program running under TSO begins to ABEND, a diagnostic message 
containing the ABEND code is written to the terminal, ABEND processing is 
halted, and control is returned to either the TMP or TEST. If the program was 
running under the control of the TEST command processor, control is returned to 
TEST and you can immediately begin to use the TEST subcommands to 
determine the cause of the error. If the program was not running under TEST, 
control is returned to the terminal monitor program. You can then enter the 
TEST command (no program name should be entered) to place the abnormally 
terminating program under control of the TEST command processor. 

Use the ABEND code to determine the type of interruption that occurred. Issue 
the WHERE subcommand to determine where the interruption occurred. 

The WHERE subcommand is especially helpful. If you enter the WHERE 
subcommand without an address, TEST displays the address of the next 
executable instruction, the related load module and CSECT names, and the 
hexadecimal offset of the displayed address. 

The instruction address, and the information returned by the WHERE 
subcommand pinpoint the error. 

Use the LIST subcommand to display the instructions leading up to the error 
condition, and to display data areas and registers used in those instructions. This 
information should be sufficient to determine the cause of the error. 
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Determining Data Set Information 



If you want to investigate the condition of any of your data sets, perform the 
following operations: 

1. Use the LISTTCB subcommand to display the TCB for the terminating task. 

2. Use the contents of the TCBDEB field as an operand of the LISTDEB 
subcommand to gain access to the data extent block queue. 

3. Use the contents of the DEBDCBAD field in each of the DEBs in the DEB 
queue, or the addresses of any DCB macro instructions coded within your 
program, as an operand of the LISTDCB macro instruction to list the data 
control blocks. 

These control blocks contain the addresses of other control blocks useful in the 
debugging process. See Data Areas. 
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Appendix A. Notation for Defining Macro Instructions 



The notation used in this publication is described in the following paragraphs. 

1. The set of symbols listed below are used to define macro instructions, but 
should never be written in the actual macro instruction: 

hyphen 
underscore _ 
braces { } 

brackets [ ] 
ellipsis 

The special uses of these symbols are explained in paragraphs 4-8. 

2. Uppercase letters and words, numbers, and the set of symbols listed below 
should be written in macro instructions exactly as shown in the definition: 

apostrophe ' 
asterisk * 
comma , 
equal sign = 
parentheses ( ) 
period 

3. Lowercase letters, words, and symbols appearing in a macro instruction 
definition represent variables for which specific information should be 
substituted in the actual macro instruction. 

Example: If name appears in a macro instruction definition, a specific value 
(for example, ALPHA) should be substituted for the variable in the actual 
macro instruction. 

4. Braces group related items, such as alternatives. 
Example: The representation 



ALPHA= ( 



A 

B ,D) 

C 



indicates that a choice should be made among the items enclosed within the 
braces. If A is selected, the result is ALPHA = (A,D). If B is selected, the 
result can be either ALPHA = (,D) or ALPHA = (B,D). 
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5. Brackets also group related items; however, everything within the brackets is 
optional and may be omitted. 

Example: The representation 



ALPHA= ( 



,D) 



indicates that a choice can be made among the items enclosed within the 
brackets or that the items within the brackets can be omitted. If B is selected, 
the result is: ALPHA = (B,D). If no choice is made, the result is: 
ALPHA = (,D). 

6. Hyphens join lowercase letters, words, and symbols to form a single variable. 

Example: If member-name appears in a macro instruction definition, a 
specific value (for example, BETA) should be substituted for the variable in 
the actual macro instruction. 

7. An underscore indicates a default option. If an underscored alternative is 
selected, it need not be written in the actual macro instruction. 

Example: The representation 

A (Al 

B or }B 

. C (C) 

indicates that either A or B or C should be selected; however, if B is selected, 
it need not be written because it is the default option. 

8. An ellipsis indicates that the preceding item or group of items can be repeated 
more than once in succession. 

Example: The representation 

ALPHA [ ,BETA] . . . 

indicates that ALPHA can appear alone or can be followed by ,BETA any 
number of times in succession. 

Note: To designate register and register 1 on a macro invocation, use (0) and 
(1), respectively. You cannot use a symbolic variable to designate these registers. 
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Appendix B. Using VTAM Full-Screen Mode 



This appendix outlines the steps for writing a full-screen command processor, 
describes the full-screen protection responsibilities that you must consider when 
writing an attention exit routine, and contains several examples illustrating the 
processing that occurs when running a full-screen command processor. You need 
to use the following macros when writing a full-screen command processor: 

STFSMODE Set full-screen mode. 

STLINENO Set the line number. 

STTMPMD Set terminal display manager options. 

TGET Get a line from the terminal. 

TPUT Write a line to the terminal. 

Earlier sections of this book contain the complete syntax of each of these macros; 
this appendix discusses only the pertinent keywords. 



Writing a Full-Screen Command Processor 



Follow these steps when writing a full-screen command processor: 

1 . Set full-screen mode on. 

2. If replacing a display terminal manager, such as Session Manager, put the 
command processor in control. 

3. Write to and get information from the terminal as necessary. 

4. Exit and reenter full-screen mode as necessary. 

5. Terminate the full-screen command processor and, if it replaced a display 
terminal manager, return control to the display terminal manager. 

Each of these steps is described in more detail on the following pages. Figure B-l 
shows the macros used when writing a full-screen command processor. 
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(1) 


STFSMODE ON,INITIAL = 


= YES Set full-screen mode on 


(2) 


STTMPMD ON 


Give control to the command processor 


(3) 


TPUT FULLSCR 


Issue a full-screen message 




TGET ASIS 


Get input from the terminal 


(4) 


STLINENOLINE=l 


Clear the screen and exit 
full-screen mode expecting 
to reenter it later 




TPUT EDIT 


Issue a non-full screen message 




STFSMODE ON 


Reenter full-screen mode 




TPUT FULLSCR 


Issue a full-screen message 




TGET ASIS 


Obtain RESHOW request 




TPUT FULLSCR 


Reissue the previous full-screen message 




TGET ASIS 


Get input from the terminal 


(5) 


STLINENOLINE=l 


Clear the screen 




STFSMODE OFF 


Exit full-screen mode and set defaults 




STTMPMD OFF 


Return control to the display 
terminal manager 




TPUT EDIT 


Display session summary information 



Figure B-l. Macros Used to Write a Full-Screen Command Processor 



(1) Set Full-Screen Mode On 



Use the STFSMODE macro to set full screen mode on. This macro prevents 
unexpected non-full-screen messages from overlaying the screen. For example, 
unexpected messages from the operator or from other TSO users could cause 
invalid input to be sent to the command processor. Also, STFSMODE prevents 
full-screen messages from overlaying unexpected non-full-screen messages before 
the user has a chance to read them. 

To prevent unnecessary protection of the screen contents, specify INITIAL = YES 
when you use the STFSMODE macro. If you specify INITIAL = YES and the 
first message is a full-screen message, TSO/VTAM does not display three asterisks 
at the terminal (which would require the user to press the ENTER key). 
TSO/VTAM sets the INITIAL keyword indicator to NO after the command 
processor sends the first full screen of information. For subsequent full screens of 
output that follow non-full screens of output, TSO/VTAM displays the three 
asterisks at the terminal before processing the full-screen output. See "Examples 
of Full-Screen Command Processor Operation" at the end of this Appendix for a 
description of the processing that takes place when INITIAL = YES and 
INITIAL = NO. 
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TERMINAL BREAK Support for Full-Screen Mode: When a command 
processor establishes full-screen mode, VTAM treats all devices as if the terminal 
user had entered the TERMINAL NOBREAK command. If the user specifies 
TERMINAL BREAK before a full-screen command processor is invoked, VTAM 
supports the BREAK mode before the command processor enters full-screen 
mode and whenever the command processor exits from full-screen mode. See 
TSO Extensions Command Language Reference for a description of the 
TERMINAL command. 



(2) Give Control to the Command Processor 



If your command processor replaces a display terminal manager, such as Session 
Manager, use the STTMPMD macro to put the command processor in control. 
If you do not use this macro, the display terminal manager traps line-mode 
messages so the user does not see them in the ordinary way. If your command 
processor does not replace a display terminal manager, you do not need this 
macro. 



(3) Write to and Get Information from the Terminal 



Use the TPUT and TGET macros to provide interaction between the user and the 
command processor. TPUT FULLSCR, TPUT NOEDIT, and TPG transmit a 
full-screen of output to the terminal. 

Unlocking the Keyboard: When a command processor issues a TGET following a 
TPUT FULLSCR, VTAM unlocks the display keyboard. When a command 
processor issues a TGET following a TPUT NOEDIT or a TPG, VTAM does not 
unlock the keyboard. Users of TPUT NOEDIT and TPG are responsible for all 
device command and write-control-character bit settings. 

Receiving Data: TGET ASIS reads a full screen of input containing the user's 
reply from the terminal. You can also use the NOEDIT keyword on the 
STFSMODE macro along with the TGET macro to get a full-screen message 
from the terminal. 

NOEDIT Mode: To obtain a full screen of input (via a TGET macro) that is not 
edited in any way, the command processor can specify the NOEDIT keyword on 
STFSMODE. Regardless of the options the command processor specifies on the 
TGET macro, in NOEDIT mode, VTAM does not edit the data, break it into 
separate input lines, or modify it. VTAM receives the input from the terminal 
and puts it on the input queue intact. To establish NOEDIT mode, the command 
processor must issue: 

STFSMODE ON,NOEDIT=YES 

Use of the NOEDIT keyword has no effect on the treatment of TPUTs and 
TPGs. 
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Protection of Screen Contents: When non-full-screen messages are issued in 
full-screen mode, TSO/VTAM clears the screen and sends the non-full-screen 
messages to the screen. When the next full-screen message is issued, TSO/VTAM 
protects the screen contents in order to allow the user time to read the 
non-full-screen messages. TSO/VTAM protects the screen by displaying three 
asterisks (***) after the last non-full-screen message and unlocking the keyboard. 
When finished reading the screen, the user presses ENTER to allow full-screen 
processing to resume. 

Restoration of Screen Contents: As part of the screen protection function, 
TSO/VTAM discards the full-screen message that immediately follows 
non-full-screen messages, unless issued with the HOLD option of the TPUT 
macro. To receive the RESHOW code, the full-screen command processor must 
issue a TGET macro after every TPUT FULLSCR macro. 

The RESHOW indicator tells the command processor to completely restore the 
screen contents. That is, the command processor must reissue the previous 
full-screen message. See "Examples of Full-Screen Command Processor 
Operation" at the end of this Appendix for an example of RESHOW processing. 

RESHOW requests can come from VTAM and from users. Users can request a 
restoration of the screen by pressing the RESHOW key. The VTAM default 
RESHOW code is X'6E', which represents the PA2 key. If the command 
processor uses a PF key for the RESHOW key, it must specify the RSHWKEY 
keyword on the STFSMODE macro when it first turns on full-screen mode. To 
set the RESHOW key, issue: 

STFSMODE ON,RSHWKEY=n 

where n is the PF key number. VTAM uses the hexadecimal representation of the 
specified PF key as the RESHOW code. 



(4) Exiting and Reentering Full-Screen Mode 



If the command processor issues non-full-screen messages (or invokes routines 
that issue non-full-screen messages), it can issue the STLINENO macro to set 
full-screen mode off and to set the line number for the next non-full-screen 
message. In so doing, the command processor eliminates the screen protection 
function and determines where the next non-full-screen message appears. If the 
line number is set to 1, VTAM clears the screen. When the command processor 
issues the last non-full-screen message (or when the invoked routine returns 
control to the command processor), the command processor must issue 
STFSMODE ON to reestablish full-screen mode. The command processor must 
issue the STFSMODE macro before it issues the next full-screen message macro. 

If the command processor exits full-screen mode, expecting to reenter full-screen 
mode at a later time before termination, the command processor must use 
STLINENO to set full-screen mode off. (Use of STFSMODE to set the mode off 
results in the RESHOW key being set to the default.) After a TGET request, the 
command processor can issue: 

STLINENO LINE=n 
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where n is the desired line number. It does not have to specify MODE = OFF on 
the STLINENO macro because that is the default for the MODE keyword. 

When all non-full-screen messages are completed, issue STFSMODE ON before 
issuing the next full-screen message macro. When the command processor returns 
to full-screen mode, it must issue the TGET macro to read the RESHOW request 
in the input queue. It can then continue to transmit and receive information from 
the terminal. 

You may want either to clear part of the screen before issuing STLINENO, or to 
display information that is to remain on the screen after the STLINENO macro is 
issued. In either case, issue a full-screen TPUT or TPG macro (including the 
HOLD option) before issuing the STLINENO. The HOLD option specifies that 
the program that issued the TPG macro cannot continue its processing until the 
output line is written to the terminal or deleted. Therefore, the full-screen 
message reaches the terminal before the STLINENO macro takes effect. 

Clearing the Terminal Screen: Because VTAM clears the screen when the line 
number is set to 1, STLINENO LINE = 1 is an efficient way for the command 
processor to clear the screen. Use of a full-screen TPUT or TPG macro 
(including the HOLD option) to clear the screen reduces performance because it 
causes a swap-out of the address space to wait for the I/O to complete. 



(5) Full-Screen Command Processor Termination 



When a TGET is satisfied with data that causes the command processor to begin 
exit processing, the following termination procedure is recommended: 

STLINENO LINE = 1 Causes VTAM to clear the screen. 

STFSMODE OFF Exits full-screen mode and resets the RESHOW key and NOEDIT mode 

to the defaults. 

STTMPMD OFF Returns control to a display terminal manager, such as Session Manager. 

non-full-screen TPUTs Optional macros that provide session summary information or other types 

of termination information. 

If the command processor issues a TPUT or TPG macro before (or instead of) 
issuing the STLINENO macro, it must use the HOLD option to guarantee that 
the message reaches the terminal before VTAM sets full-screen mode off. If the 
macro is handling a full-screen message, the command processor must issue a 
TCLEARQ INPUT macro just before termination to clear the RESHOW code 
that VTAM put on the input queue for screen protection. 



Full-Screen Protection Responsibilities of Attention Exit Routines 



To maintain screen protection when the user presses the PA1 or ATTENTION 
key, the command processor must have an attention exit routine. When the 
terminal user presses the PA1 or ATTENTION key, VTAM sets FULLSCR to 
OFF, the RESHOW key to the default, and NOEDIT mode to NO. If the 
command processor does not have an attention exit and the user presses ENTER 
(in response to the attention indication), the command processor resumes 
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execution at the point of interruption with these default values. If the command 
processor has an attention exit routine, the exit routine must issue the 
STFSMODE macro to reestablish full-screen mode, the desired RESHOW key, 
and NOEDIT mode. In this way, the attention exit routine maintains screen 
protection. 



Examples of Full-Screen Command Processor Operation 



The following examples show these functions: 

• RESHOW in full-screen message processing 

• INITIAL = YES on the STFSMODE macro when the first message is a 
full-screen message 

• INITIAL = YES on the STFSMODE macro when the first message is a 
non-full-screen message 

• INITIAL = NO on the STFSMODE macro. 

Each example consists of a chart followed by an explanation. The heading for 
each chart list the three components involved in the processing: the command 
processor, TSO/VTAM, and the terminal. The items listed under each component 
relate to that component. The numbers in the left-hand column of the charts 
refer to the events described in the explanation. The arrows in the chart indicate 
the flow of the processing. 
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Function of RESHOW in Full-Screen Message Processing 



Figure B-2 shows the use of RESHOW when a command processor, operating in 
full-screen mode, issues a full-screen message while non-full-screen messages are 
being displayed at the terminal. 



Command Processor 



TSO/VTAM 



Terminal 



input 



non-full-screen message 1 



ENTER 
non-full-screen message 1 



non-full-screen message n ■ 



non-full-screen message n 



TPUT 

full-screen message 1 



-► *** • 



-► *** 



TGET 



RESHOW 



ENTER 



TPUT 

full-screen message 1 



full-screen message 1 



TGET 



Figure B-2. Function of RESHOW in Full-Screen Message Processing 

The following events occur in Figure B-2: 

1. When the user presses the ENTER key to send input to the command 
processor, TSO/VTAM: 

• Clears the screen. 

• Sounds the alarm (if the terminal has an alarm). 

• Displays non-full-screen messages. The operator or some other user 
could have sent these messages. 

2. As long as TSO/VTAM receives non-full-screen messages, it displays them, 
one after another on the screen. 

3. The command processor's normal processing of input (see step 1) may cause 
it to send a full-screen message using the TPUT macro. When TSO/VTAM 
receives the full-screen message, it: 

• Displays three asterisks (***) at the terminal. 

• Unlocks the keyboard to ensure that the user has time to view the 
non-full-screen messages. 

• Discards the full-screen message that the command processor sent. 

4. After each full-screen message, the command processor issues a TGET macro. 
When the user presses the ENTER key to acknowledge having seen the 
non-full-screen messages, TSO/VTAM puts a RESHOW request on the input 
queue to tell the command processor to completely restore the screen 
contents. The command processor's current TGET picks up this RESHOW 
request. 

5. The command processor responds to the RESHOW request by issuing a 
full-screen TPUT to restore the screen contents. TSO/VTAM displays the 
message at the terminal. 

6. The command processor issues a TGET macro. 



Appendix B. Using VT AM Full-Screen Mode B-7 



Function of INITIAL = YES when the First Message is Full Screen 



Figure B-3 shows a situation in which the command processor specifies 
INITIAL = YES on the STFSMODE macro and issues a full-screen message as 
the first message. 



Command Processor 



STFSMODE 
INITIAL = YES 



TPUT 

full-screen message 1 



TGET 



TSO/VTAM 



READY 



Terminal 



■► READY 

— command name 



full-screen message 1 



Figure B-3. Function of INITIAL = YES when First Message is Full-Screen 

The following events occur in Figure B-3: 

1 . TSO/VTAM displays the READY message at the terminal. In response to 
the READY message, the user enters a command name, such as ISPF. The 
command processor receives the command name. 

2. The command processor issues the STFSMODE macro with INITIAL = YES. 

3. The command processor sends a full-screen message to the terminal. 
TSO/VTAM sends the message without warning because the command 
processor specified INITIAL = YES and because its previous interaction with 
the terminal involved input, not output. There is nothing to protect. 

4. The command processor issues a TGET macro. 
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Function of INITIAL = YES when the First Message is Non-Full Screen 

If the command processor specifies INITIAL = YES on the STFSMODE macro, 
and the first message is a non-full-screen message, VTAM ignores the keyword 
and protects the screen contents. Figure B-4 shows this situation. 
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Figure B-4. Function of INITIAL = YES when First Message is Non-Full-Screen 

The following events occur in Figure B-4: 

1 . TSO/VTAM displays the READY message at the terminal. In response to 
the READY message, the user enters a command name. The command 
processor receives the command name. 

2. The command processor issues the STFSMODE macro with INITIAL = YES. 

3. TSO/VTAM displays a non-full screen message. This could be a warning 
from the operator or a message from another user. 

4. The command processor sends a full-screen message to the terminal. 
TSO/VTAM protects the screen contents by sending three asterisks to the 
terminal and discarding the full-screen message. 

5. After each full-screen message, the command processor issues a TGET macro. 
When the user presses the ENTER key to acknowledge having seen the 
non-full screen message, TSO/VTAM puts a RESHOW request on the input 
queue to tell the command processor to completely restore the screen 
contents. The command processor's current TGET picks up the RESHOW 
request. 

6. The command processor responds to the RESHOW request by issuing a 
full-screen message to restore the screen contents. TSO/VTAM displays the 
full-screen message at the terminal. 

7. The command processor issues a TGET macro. 
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Function of INITIAL = NO 



If the command processor specifies INITIAL = NO or INITIAL = NO is the 
default, TSO/VTAM protects the screen before displaying the first full-screen , 
message. Figure B-5 shows an example of this situation. 



Command Processor 



TSO/VTAM 



Terminal 



READY 



READY 

command name 



STFSMODE 
INITIAL = NO 



TPUT 

full-screen message 1 



-► *** 



TGET 



RESHOW - 



ENTER 



TPUT 

full-screen message 1 



■► full-screen message 1 



TGET 



Figure B-5. Function of INITIAL = NO 

The following events occur in Figure B-5: 

1. TSO/VTAM sends a READY message to the terminal. In response to the 
READY message, the user enters a command name. The command processor 
receives the command name. 

2. The command processor issues the STFSMODE macro with INITIAL = NO. 

3. The command processor sends a full-screen message to the terminal. 
TSO/VTAM protects the screen contents by sending three asterisks to the 
screen and discarding the full-screen message that the command processor 
sent. 

4. After each full-screen message, the command processor issues a TGET macro. 
When the user presses the ENTER key, TSO/VTAM puts a RESHOW 
request on the input queue to tell the command processor to completely 
restore the screen contents. The command processor's current TGET picks 
up the RESHOW request. 

5. The command processor responds to the RESHOW request by issuing a 
full-screen message to restore the screen contents. TSO/VTAM displays the 
full-screen message at the terminal. 

6. The command processor issues a TGET macro. 
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STRING 15-14 
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records 11-4 
format only function 

difference between text insertion processing 12-54 
formatting 

HELP data set 3-10 
output line 12-51 
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effect of LIST and RANGE options on 

format 15-76 
format (general) 15-60 
types 

ADDRESS parameter 15-64 
CONSTANT 15-70 

DSNAME or DSTHING parameter 15-62 
EXPRESSION 15-75 
expression value parameter 15-66 
IKJIDENT parameter 15-75 
JOBNAME parameter 15-63 
KEYWORD parameter 15-83 
non-delimiter dependent parameter 15-75 
positional parameter 15-61 
RESERVED word 15-74 
STATEMENT NUMBER 15-72 
STRING, PSTRING, or a QSTRING 

parameter 15-61 
UID2PSWD 15-69 
USERID parameter 15-69 
VALUE parameter 15-62 
VARIABLE 15-73 
PDL 

header 15-60 
PDL (parameter descriptor list) 
naming (DSECT = ) 1 5-60 
perform a list of DAIR operations 10-17 
PGPB, PUTGET parameter block 12-2 
physical line processing 12-26 
pointer 

forward chain 12-46 

to the formatted line (PUTLINE) 12-54 



to the I/O service routine parameter block 12-2 
positional parameters 15-12 

entered as lists or ranges 15-27, 15-76 

missing 15-12 

not dependent upon delimiters 15-27 

order of coding parse macros 15-32 
PPMODE 2-5 
primary text segment 

offset of 12-52 
print inhibit (PTBYPS) 12-60, 12-65 
private HELP data set 3-11 
processing 

a source in-storage list 8-2 

attention interruptions 2-8 

modes 11-4, 12-58 

physical line 12-26 

STOP commands 2-12 
PROFILE command 8-3,12-51,12-75 
PROFILE subcommand of TEST 18-3 
program 

areas 

displaying 18-7 

displaying 1-6 

execution under TEST 18-5 

interruption at a specified location (TEST) 1-6, 
18-7 
program access to CLIST variables 6-1 
program access to CLIST variables (see CLIST) 
program execution 

examining 18-7 
program interface to other programs 5-2 
program interface to TSO commands 5-2 
program residency 

below 16 megabytes 4-2, 4-3 
program status word (PSW) 

displaying 1-6, 18-9 
program-id 

statement number parameter 1 5-25 

variable parameter 15-24 
prompt message 

processing 12-75 

second level 1 5-86 
prompt mode HELP function 

definition of 3-6 

importance of ECTNOQPR bit 3-6 

making active for subcommands 3-6 

relationship to second level messages 8-2 

restrictions on 3-6 

updating HELP members for 3-14 
prompting 15-86 

for missing operands 1 5-86 

inhibiting 12-71 

input wait after 12-76 

messages 8-1 

responses 15-86 

return codes 15-101 

scanning the input buffer 15-1 

translation to upper case 1 5-83 

types of command parameters recognized 15-12 

user at the terminal 15-86 
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using the parse service routine 
examples 15-86 
PROTECT subcommand of TEST 18-3 
protection of screen contents B-4 
PSTRING 

syntax of 15-20 
PSW 

at time of abnormal termination 2-8 

displaying 1-6 
PTPB, PUTLINE parameter block 12-2 
purging the second level message chain 12-55 
PUT macro instruction 11-3 
PUTGET buffer 

freeing 12-76 
PUTGET macro instruction 

coding example 12-78 

format 12-59, 12-64 

OUTPUT = 12-74 
PUTGET parameter block 12-69 

initializing 12-69 
PUTGET processing 12-74 
PUTGET service routine 12-58 

basic functions of 1-3 

coding example 12-78 

command processor use of 3-4 

control blocks 12-73, 12-77 

description 12-58 

input buffer format 12-76 

input line format 12-76 

macro instruction 

execute form 12-63 
list form 12-59 

mode message processing 12-74 

no output line 12-74 

operands 12-59, 12-64 

output line descriptor (OLD) 12-72 

output line formats 12-71 

parameter block (PGPB) 12-69 

passing message lines to 12-72 

PAUSE processing 12-75 

processing of second level messages 8-2 

prompt message processing 12-75 

providing the GET (ATTN) function only 12-60 

question mark processing 12-75 

return codes 12-80 

sources of input 12-58,12-74 

text insertion 12-72 

TGET options (TERMGET) 12-62, 12-67 

TPUT options (TERMPUT) 12-60, 12-66 

types of output line descriptor 12-72 

user abend 204 12-81 
PUTLINE functions for message lines 12-48 
PUTLINE macro instruction 

coding example 12-45 

format of 12-33, 12-34 
PUTLINE parameter block 12-43 

initializing 12-42 
PUTLINE service routine 12-33 

basic functions of 1-3 

building a second-level informational chain 12-55 



coding examples of 12-53 
command processor use of 3-4 
control blocks 12-50 
control flags 12-43 
description 12-33 
format only function 12-54 
macro instruction 

execute form 12-37 

list form 12-34 
message line processing 12-51 
message processing control blocks 12-50 
operands 12-34, 12-37 
output line descriptor (OLD) 

for multilevel message 12-49 

for single level message 12-49 
output lines 

format 12-44 
parameter block 12-43 
passing message lines to 12-49 
processing of second level messages 8-2, 12-48 
PUTLINE parameter block (PTPB) 12-42 
return codes 12-58 
stripping message identifiers 12-51 
text insertion function 12-52 
TPUT (TERMPUT) options 12-35, 12-39 
types and formats of output lines 12-44 
PUTLINE, putting a line out to the terminal 12-33 
PUTX macro instruction 11-3 



QSAM 

macro instructions 11-1 

using for terminal I/O 11-1 
QSTRING definition 15-23 
qualification 

variable parameter 15-25 
qualified address parameter 15-15 

formats 15-15 
qualifier 

data name 15-25 
QUALIFY subcommand of TEST 18-2 
question mark 

entered after ABEND 2-7 

processing 12-74 

processing by I/O service routines 12-1 
quoted string (QSTRING) 

syntax of 15-23 



R 



range 

use of (general) 1 5-28 
range option 

how to use 15-77 
READ macro instruction 11-3 
read partition query structured field 13-7 
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reading a record from the terminal (the READ macro 

instruction) 11-3 
reason codes-IKJEFTSR 5-7 
receive control 

in 24-bit addressing mode 4-2 

in 31 -bit addressing mode 4-2 
record formats supported under TSO 11-4 
record returned by GETLINE 

identifying the source of 12-27 
reentering full-screen mode B-4 
register 

changing contents 1-6,18-9 

displaying 1 -6 

floating-point 15-14 

general 15-14 
register contents 

when TMP is attached 2-2 
register form 

TPUT macro 13-2 
relationship between primary and secondary segments 

(PUTLINE) 12-52 
relative address parameter 15-14 
RENAME subcommand of TEST 1 8-3 
requesting 

a command 2-3 

a new command or subcommand 1-4 
RESHOW B-4, B-7 
residency 

input 

above or below 16 megabytes 4-4 

above 16 megabytes 4-2, 4-4 

below 16 megabytes 4-2, 4-3, 4-4, 4-5 

program 4-1 

requirements 4-2 
responding to 

abnormal terminations 1-4 

attention interruptions 1 -4 
restoration of screen contents B-4 
restrictions 

addressing for TEST 1 8-4 

non-delimiter dependent parameters 1 5-27 

on executing exclusively in 3 1 -bit mode 4-3 

on invoking programs with 24-bit dependencies 4-3 
results of command scan 15-8 
retrieving information about commands and 

subcommands 3-10 
return codes 

from command scan 1 5-9 

from DAIR 10-23 

from dynamic allocation 10-24 

from GETLINE 12-32 

fromGTDEVSIZ 14-2 

from GTSIZE 14-3 

from GTTERM 14-4 

from IKJEHCIR 16-3 

from LOCATE 16-3 

from parse service routine 15-101 

from PUTGET 12-80 

from PUTLINE 12-58 

from RTAUTOPT 14-5 



from SPAUTOPT 14-6 

from STACK 12-20 

from ST ATTN 14-7 

from STAUTOCP 14-8 

from STAUTOLN 14-10 

from ST AX 9-10 

fromSTBREAK 14-11 

from STCC 14-14 

from STCLEAR 14-14 

from STCOM 14-15 

from STFSMODE 14-17 

from STLINENO 14-18 

from STSIZE 14-19 

from STTIMEOU 14-21 

from STTMPMD 14-22 

from STTRAN 14-23 

from TCLEARQ 14-24 

from TGET 13-12 

from TPG 13-9 

from TPUT 13-7 

validity checking 15-85 
return codes-IKJEFTSR 5-5 
returning the value of a variable 6-8 
RMODE=ANY 

AMODE-31 4-2 
RMODE = 24 

AMODE = ANY 4-2 

AMODE = 24 4-2 

AMODE = 31 4-2 
RTAUTOPT macro instruction 14-4 
RUN subcommand of TEST 1 8-2 
running programs 

in 370-XA mode 4-2 

on an MVS/XA system 4-1 

on an MVS/370 system 4-1 



SAM terminal routines 11-2 
screen contents 

protection B-4 

restoration of B-4 
second level messages 

definition 8-1 

deleting 3-4, 8-3 

informational messages 12-55 

message chain 3-4,12-55 

messages handled by parse 15-86 

no message identifiers 12-55 

requesting 8-1 
secondary text segment 

offset of 12-52 
SEND subcommand of TEST 18-3 
separator characters 15-8, 15-12 
sequence of operations 

TEST 18-6 
sequential access method (SAM) terminal routines 

CHECK 11-4 

GET 11-3 
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PUT 11-3 

PUTX 11-3 

READ 11-3 

WRITE 11-4 
service routine interfaces 

catalog information routine (IKJEHCIR) 4-4, 7-4, 
16-1 

CLIST variable access routine (IKJCT441) 4-4 

command scan service routine (IKJSCAN) 7-4, 
15-5 

DAIR 10-2 

DAIRFAIL (IKJEFF18) 4-4, 10-24 

data type processor (IKJEBEPS) 4-3 

default service routine (IKJEHDEF) 4-4, 7-4, 17-1 

dynamic allocation interface routine 
(IKJDAIR) 4-4, 7-4 

GETLtNE service routine (IKJGETL) 4-4, 12-4 

GNRLFAIL/VSAMFAIL (IKJEFF19) 4-4, 10-26 

parse service routine (IKJPARS) 4-4, 7-4, 15-9 

PUTGET service routine (IKJPTGT) 4-4, 12-4 

PUTLINE service routine (IKJPUTL) 4-4, 12-4 

STA interface routine (IKJEHSIR) 4-3 

STACK service routine (IKJSTCK) 4-4, 12-4 

STAX 4-4,9-1 

TSO message issuer routine (IKJEFF02) 4-4, 7-4, 
8-3 

TSO service routine (IKJEFTSR) 4-4 
set full-screen mode on B-2 
setting 

addressing modes 

via BASSM or BSM 7-4 
shift-in character 15-8,15-13 
shift-out character 15-8,15-13 
single level messages 12-48 
single line data 12-44 
source 

effects on message processing 8-2 
source data set 

in storage 12-11 

adding an element to the input stack 12-6, 12-9 
sources of input 12-11 

changing 12-5 

current 12-5 
space parameter 

definition 15-23 
SPAUTOPT macro instruction 14-5 
special functions of the TMP 2-12 
specifying a terminal attention exit - the STAX 
macro 9-4 
STACK macro instruction 12-5 

execute form 12-7 

list form 12-5 
stack parameter block (STPB) 12-13 
STACK service routine 12-5 

basic functions of 1-3 

coding example of macro 12-12,12-15 

command processor use of 3-3 

control block structures 
in-storage list 12-17 

description 12-5 



element code 12-12 

input source 12-11 

list source descriptor (LSD) 12-13 

macro instruction 

execute form 12-7 
list form 12-5 

parameter block 12-12 

return codes 12-20 
STAE macro 3-7 

STAI operand of ATTACH macro 3-7 
standard form 

TGET macro 13-10 

TPUT macro 13-2 
ST ATTN macro instruction 14-6 
STATUS subcommand of TEST 18-3 
STAUTOCP macro instruction 14-8 
STAUTOLN macro instruction 14-9 
STAX parameter list (STPL) 9-7 
STAX service routine 9-1 

coding example of macro 9-8 

deferring attention exits 9-2 

macro instruction format 9-4 

parameter list 9-7 
STBREAK macro instruction 14-10 
STCC macro instruction 14-12 
STCLEAR macro instruction 14-14 
STCOM macro instruction 14-15 
STFSMODE B-l,B-2 
STFSMODE macro instruction 14-15 
STLINENO B-l 

STLINENO macro instruction 14-17 
STOP command processing 2-12 
STOP/MODIFY event control block (ECB) 2-12 
storage areas 

displaying 18-7 
STPB, STACK parameter block 12-2 
string 

definition 15-13 
stripping message identifiers 12-51 
STSIZE macro instruction 14-18 
STTIMEOU macro instruction 14-20 
STTMPMD B-l 

STTMPMD macro instruction 14-21 
STTRAN macro instruction 14-22 
subcommand name 

checking syntax 1-3 

syntactically valid 15-1 
subcommand processors 

abnormally terminating 3-7 
subcommands of TEST 18-2 
subfieid descriptions 15-57 

subfields associated with keyword parameters 15-57 
SUBMIT subcommand of TEST 1 8-3 
subscript 

statement number parameter 1 5-25 

variable parameter 15-25 
substitute mode of PUT and PUTX macros 11-3 
subtask ABEND 2-6 
SVC 93 13-1 
symbolic address 
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for TEST 18-4 

syntax of 15-15 
SYNCH macro instruction 

to invoke TEST command processor 2-7 
syntax 

notation for defining macro instructions Arl 
SYSABEND data set 2-8 
SYSMDUMP data set 2-8 
SYSOUT data set 

allocation of 10-18 
system catalog 

searching for data set name 10-5 
system code 337 11-3 
SYSUDUMP data set 2-8 
SYS1.CMDLIB 3-2 
SYS1. HELP - the HELP data set 

attributes of 3-10 

updating 3-11 



TAXE 9-1 

TCLEARQ macro instruction 14-24 

TERM = TS (operand of DD statement) 1 1-5 

terminal 

allocating a data set to 10-14 

communicating with 1-2 
terminal as input source 12-11, 12-15 
terminal attention exit element (TAXE) 9-1 
terminal attention interruption element (TAIE) 2-11 
TERMINAL BREAK 

use of B-3 
terminal control macro instruction 14-1 
terminal element 

adding to input stack 12-5, 12-9 
coding example 12-15 
terminal monitor program (TMP) 

basic functions 1-2 

conditions to which it must respond 2-2 

control blocks passed to command processors 7-3 

description 1-1 

ESTAE exit 2-7 

fresh copy after ABEND 2-8 

functions of 1-2 

initialization 2-2 

intercepting a task ABEND 2-5,2-7 

link to TEST command processor 2-7 

obtaining a command 2-3 

parameters passed to a command processor 2-5 

processing a STOP command 2-12 

processing an attention interruption 2-8 

shared subpool 2-3 

special functions of 2-12 

STOP/MODIFY ECB 2-12 

TIME function 2-12 

using command scan 2-12 
TERMINAL subcommand of TEST 18-3 
terminal user's options after ABEND 2-7 
TEST command 



addressing restrictions 18-4 

ALLOCATE subcommand 18-2 

AND subcommand 18-2 

AT subcommand 18-7 

breakpoints 

establishing and removing 18-7 

changing 

data areas 18-9 
instructions 18-9 
register contents 18-9 

CP or NOCP operand 18-5 

definition 17-1 

determining data set information 18-11 

displaying selected areas of storage 18-7 

entering the command 18-6 

EQUATE subcommand 18-2 

establishing and removing breakpoints 18-7 

executing a program under control of 18-5 

forcing execution of program subroutines 18-10 

GETMAIN subcommand 18-2, 18-9 

issuing the 18-6 

LIST subcommand 18-2, 18-8 

LISTDCB subcommand 18-9 

LISTDEB subcommand 18-8 

LISTMAP subcommand 18-8 

LISTPSW subcommand 18-9 

LISTTCB subcommand 18-8 

NOCP or CP operand 18-5 

OFF subcommand 18-2, 18-7 

OR subcommand 18-2, 18-3 

PROFILE subcommand 18-3 

PROTECT subcommand 18-3 

QUALIFY subcommand 18-3 

RENAME subcommand 18-3 

restrictions 

addressing 18-4 

SEND subcommand 18-3 

sequence of operations 18-6 

STATUS subcommand 18-3 

subcommands 1 8-2 

SUBMIT subcommand 18-3 

symbol processing 18-4 

testing a newly-written TMP or CP 17-1 

testing after a program ABEND 18-10 

UNALLOC subcommand 18-3 

when to use 18-3 

WHERE subcommand 18-2, 18-10 
testing 

currently executing program 18-3 

online 1-5 

program not currently executing 18-4 
testing a CP 1-5 
testing a TMP 1-5 
testing a TMP or CP 17-1 
text insertion function of PUTLINE 12-52 
TGET B-l, B-3 

basic functions 1-3 

coding example 13-17 

definition 13-10 

execute form 13-10 
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format 13-10 

list form 13-10 

macro description 13-10 

number of bytes moved 13-11 

register form 13-10 

return codes 13-12 

standard form 13-10 

used by GET 11-3 

used by READ 11-3 
TGET ASIS B-3 
TGET/TPUT SVC 

parameter registers 13-13 
TGET/TPUT/TPG SVC 13-1 

macro instructions 13-1, 13-7 
TIME function of the TMP 2- 1 2 
TPG B-3 

basic functions 1-3 

codes returned by 13-9 

definition 13-7 

execute form 13-7 

list form 13-7 

macro description 13-7 

return codes 13-9 

standard form 13-7 
TPUT B-l, B-3 

basic functions 1-3 

codes returned by 13-7 

coding example 13-17,13-18 

definition 13-1 

execute form 13-2 

list form 13-2 

macro description 13-1 

register form 13-2 

return codes 13-7 

standard form 13-2 

used by PUT and PUTX 1 1 -3 

used by WRITE 11-4 
TPUT FULLSCR B-3 
TPUT NOEDIT B-3 
translation to upper case 1 5-83 
TSEVENT macro instruction 2-5 
TSO I/O service routines 12-1 
TSO message issuer routine (IKJEFF02) 8-3 
TSO service facility 

See TSO service routine 
TSO service routine 

ABEND processing 5-4, 5-5 

ABEND reason code 5-5 

flags 5-4 

function buffer 5-5 

function buffer length 5-5 

function flag 5-5 
command 5-5 
program 5-5 

function reason code 5-5 

function return code 5-5 

IKJEFTSR description 1-1 

IKJEFTSR return codes 5-5 

introduction 5-1 

invoking the TSO service routine 5-2 



optional parameter 5-5 
parameters 5-4, 5-5 

ABEND processing 5-4 

ABEND reason code 5-5 

command function flag 5-5 

fifth parameter 5-5 

first parameter 5-4, 5-5 

flags 5-4 

fourth parameter 5-5 

function buffer 5-5 

function flag 5-5 

function reason code 5-5 

function return code 5-5 

functional parameter list 5-5 

program function flag 5-5 

program parameter list 5-5 

second parameter 5-5 

seventh parameter 5-5 

sixth parameter 5-5 

third parameter 5-5 
program interface to TSO commands or 

programs 5-2 
second parameter 5-5 

function buffer 5-5 
their uses and interfaces 

IKJDAIR 10-2 
TSO service routines 
control blocks 

IKJCPPL 7-1 

IKJCSOA 7-1 

IKJCSPL 7-1 

IKJDAPL 7-1 

IKJDAPOC 7-1 

IKJDAP00 7-1 

IKJDAP04 7-1 

IKJDAP08 7-1 

IKJDAP1C 7-1 

IKJDAP10 7-1 

IKJDAP14 7-1 

IKJDAP18 7-1 

IKJDAP2C 7-1 

IKJDAP24 7-1 

IKJDAP28 7-1 

IKJDAP30 7-1 

IKJDAP34 7-1 

IKJDFPB 7-1 

IKJDFPL 7-1 

IKJECT 7-1 



IKJEFFDF 
IKJEFFGF 
IKJEFFMT 
IKJEGTPB 



7-1 
7-1 
7-1 
7-1 



IKJIOPL 7-1 
IKJLSD 7-1 
IKJPGPB 7-1 
IKJPPL 7-1 
IKJPSCB 7-1 
IKJPTPB 7-1 
IKJSTPB 7-1 
IKJSTPL 7-1 
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IKJTAIE 7-1 
IKJTAXE 7-1 
IKJTMPWA 7-1 
1KJTPL 7-1 
IKJUPT 7-1 
processing terminal requests 
their uses and interfaces 
IKJCSOA 15-6 
IKJCSPL 15-5 
IKJENDP 15-57 
IKJGTPB 12-27 
IKJIDENT 15-46 
IKJIOPL 12-2 
IKJKEYWD 15-52 
IKJNAME 15-54 
1KJOPER 15-40 
IKJPARM 15-31 
IKJPOSIT 15-32 
IKJPPL 15-10 
IKJRLSA 15-58 
IKJRSVWD 15-44 
IKJSUBF 15-56 
passing control to 7-2 

TSOLNK 5-2 

TSVT 6-1 
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6-14 



BSAM for terminal I/O 10-27 
command scan service routine (IKJSCAN) 
DAIR 10-2 

parse macro instructions 15-30 
parse service routine (IKJPARS) 15-9 
PUTLINE format only function 12-54 
PUTLINE text insertion function 12-52 
QSAM for terminal I/O 10-27 
terminal control macro instructions 14-1 
TGET/TPUT/TPG SVC for terminal I/O 
TSO I/O service routines 12-1 
VTAM full-screen mode B-l 
utility data set allocation 10-8 



validity check parameter list 15-85 
validity checking exits 3-6 
value parameter definition 15-14 
variable parameter 15-24 
variables 

CLIST 6-1 
verb number 

statement number parameter 15-25 
virtual storage map of a program 

displaying 1 -6 
VSAMFAIL routine 10-26 



15-3 



12-81 



UID2PSWD 

definition 15-21 
UNALLOC subcommand of TEST 1 8-3 
update the value of a variable 6-3, 6-5 
updating existing HELP members 3-15 
updating SYS 1. HELP 3-11 
user 

communicating with 1-2 
user LOGON PROC 2-1 

DYNAMNBR parameter on EXEC statement 2-1 

example 2-1 
use rid 

definition and format 15-21 
using 
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WHERE (subcommand of TEST) 18-10 
write information to the terminal B-3 
WRITE macro instruction 11-4 
writing help members 3-11 



31 -bit addressing 

general interface considerations 4-1 
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